Contents
CleanSheet Help Contents

Ordering Info

CleanSheet version 1.1 costs £41.70+Tax+Delivery which is £52.70 all inclusive in the UK, for foreign orders, please call first. (Price subject to change without notice).

WorkingTitle
129 Woodstock Rd
Yarnton
Kidlington
Oxon, OX5 1PT
United Kingdom
Tel/Fax (+44) (0)865 370175
Email: WorkingTitle@cix.compulink.co.uk

Introduction

Copyright

Welcome to CleanSheet

Getting Started Quickly

General Topics

Edit Mode

Use Mode

Menus

Pipes

Tags

Button Bar

Window Management

Pallette of Objects

Conventions Used

Functions

Data Types

Function Arguments

Function Errors

Vague Logic

General Mathematical Functions and Operators

General Functions, Listed

Geometric Functions, Listed

Trigonometric Functions, Listed

Array Manipulation Functions, Listed

Financial Functions, Listed

Statistical Functions, Listed

Debugging

Debugging a Sheet

Debugging Computer Objects

Technical Support

Objects

 Input Table	 Object Input Box

 Text Box (Input)	 Button Group

 Slider Input	 Tumbler

 Density Graph (Input)	 Polar Graph (Input)

 XY Scatter Input	 Random Generator

 Output Table	 Hard Copy Object

 Filing Clerk	 Line/Column/Area Graph

 Density Graph (Output)	 Pie Chart

 Segment Chart	 Line/Bar/Area Graph

 Polar Graph (Output)	 XY Scatter Graph

 3D Graph	 Calculator Object

 Cog Calculation	 Summation

 Array Dissector	 Overlay Object

 Computer Object	 Sum Product

 Product	 Savings and Loans

 Toolbox - General	 Toolbox - Financial

Toolbox - Statistical	 Transpose Object

 XY Scatter (Calculation)	 Polar Graph (Calculation)

 Inverter	 Chi-Square Object

 Converter	 Curve Fit Object

 Evaluator Object	 Database Filter

 Database Sort	 Database Merge

 Lookup Object	 Database Splicer

 Database Extractor	 Database Chopper

 Counter	 Database Comparator

 Database Trimmer	 AB to C Switch

 C to AB Switch	 Junction Object

 Switch	 Announcer Object

 Reporter Object	 Solution Search


Copyright Notice
Copyright

CleanSheet, all its programs, examples, help file and documentation are Copyright Working Title, 1992, 1993, 1994 All rights reserved.

Purchasing CleanSheet allows you, and only you, to use it. For this purpose you may keep as many copies of the program as you need, provided that you can clearly establish that they are for your own personal use. If you sell your package, you must destroy all copies you have and immediately notify Working Title of its change of ownership.

This does not entitled you to:

Copy the documentation

Allow copies to be used by any third party

Distribute in any form, any part of CleanSheet, its examples, help files or documentation.

One person - one copy of CleanSheet.

Every copy of CleanSheet is listed against its purchaser, if copies of CleanSheet registered to you are pirated, or even used by someone not listed as having the right to use it, it is you we will pursue first.


Debugging a Sheet

Introduction

Sheet errors are called bugs, and finding these errors is called debugging.

When you have designed a sheet it is essential to check that it works the way you expected. If the results you get out from the sheet don't match the results that are supposed to come from the sheet what can you do?

General Aim

The aim in debugging is to pin the bug down to within two limits. You then tighten those limits until you can identify exactly where the bug is. A golden rule exists here - when you can't see a bug in a section - subdivide the section and pin it down further.

To help you do this, you can see the contents of any data pipe by double clicking on it. As the sheet is recalculated, you can watch these data pipes change.

Fix the Bugs you Know

Fix the bugs you know about before chasing the ones you don't. It is very easy to think 'this bug couldn't possibly cause that result - so there must be another somewhere else in the sheet'' - How can you be so sure? You were fallible enough to make the error in the first place - maybe you're fallible enough not to understand all its consequences.

Repeat Repeat Repeat

To track down a bug, the problem must be repeatable, otherwise any test you do has no value - was the bug really not in that section or did it simply not occur at all that time? You must find the data that fails in a known, predictable, repeatable way so that you can use this as a test.

Error Objects

If the result from the sheet is an error object, then you can select 'Colour Errors Red' on the Pipe Options dialogue, and then recalculate the sheet.

You will then be able to follow the Red (error) pipes back to the object that they started from. The next step is to check the parameters fed into that object - maybe the parameters are wrong, maybe you haven't pinned the error down - you must check.

Understanding the error may help you, for this you should lookup the error in Function Errors.

Circular Reference

When you are faced with a circular reference (objects connected in a loop), it is not possible to pin the error down to a single object, since there may be many objects in the loop. Fortunately there is a simple technique for finding these references: Select 'Colour Circular References' on the Pipe Options dialogue. When you recalculate the sheet, the circular reference pipes will be highlighted, you can then fix the faulty connection that caused the problem.

Divide into Sections

Your sheet probably consists of several sections, each section calculating a different part of the result. As such it can be broken down into those sections and each section checked in-tern to see if an error exists.

Once you have found a section with a fault - fix it and retest to check it's fixed.

Breaking a Sheet

When faced with a sheet that consists of many calculation sections, it is always best to break the pipes into the sections and feed in test data into the suspect one.

By breaking the connection with the rest of the sheet you are isolating the problem. If the result is correct with this test data, then the problem is higher up the sheet.

Knowing where the bug isn't is just as worthwhile as knowing where it is, both help you confine the bug further.

Common Errors

The commonest errors within CleanSheet are to do with arrays - for this reason you must be familiar with array notation. Consider the following examples:

{{10,20,30,40))	This is a 2 dimensional column array.

{10,20,30,40}	This is a 1 dimensional array (these are always displayed as rows)

{{10},{20},{30},{40}}	This is a 2 dimensional row array

Look at the second two examples, they would both be displayed as rows on an Output Table object, but one is a 1 dimensional array and the other a two dimensional array.

Finishing Off

Once you've pinned the bug down to a very small part of your sheet the bug usually becomes obvious. When it isn't ask yourself honestly - can I pin it down any further? When you can't subdivide further you need a different technique - replacement. Approach the problem a different way, use different methods to achieve the same thing.

Finally when that still doesn't work, take a step back and re-examine your debugging technique. Did you cut a corner along the way. Did you ever say to yourself 'The bug couldn't be there, I won't check that'.


Debugging a Computer Object

Double click on the Computer Object to open an editor window to it.

Leave the text editor window open with the program displayed.

Run the sheet by either Clicking on Manual Recalculation or if you have automatic recalculation switched on, change an input object to cause a recalculation.

When the Computer object executes, its window will be topped and the line being executed will be highlighted.

The Inspect Variables Dialogue will appear which allows you to set the speed of execution and examine the variables within the program.

If you have several Computer Objects on screen, you may wish to trace several of them. To do this simply leave text edit windows open for several of the computer objects. As each object is recalculated, its text edit window will be topped and the Inspect Variables dialogue will appear for each of them in-tern.


Technical Support

Technical support is by far the most expensive item provided as part of any piece of computer software. With low price software the scope for technical support is very limited, and it only takes small amount of technical support before the sale goes into loss.

With this in mind we have to insist that you follow the technical support rules:

Technical support is not a design service. Do not ask how to design a sheet to tackle a particular problem - that is your responsibility not ours.

Read all the relevant sections of the help. If you ask a question that is answered in the help, you will be referred to a help topic, it will not be explained to you over the phone or by letter.

If you wonder if doing A will result in B - try it and see, don't call.

Don't ask questions that aren't about CleanSheet, we may be able to answer questions about Windows or File Manager or the Desktop, but so can Microsoft, call them.

Remember that you are in the best position to fix your problem. You know what you are trying, you know the computer and system you are running, we don't. The best we can do is to try and draw the answer out of you.

Have the computer next to the phone. Running backwards and forwards between computer and phone is not sufficient, passing messages person to person is not sufficient.

When writing in with a technical problem, keep it relevant. Don't mix sales requests with technical support, don't go into detail about other products. Similarly when talking on the phone, kept it relevant and short, remember that other people may be in the phone queue waiting for an answer to their questions.

Disk replacement, if a disks goes wrong then you can return the faulty disk within 30 days of purchasing the package and we will replace it free of charge. After 30 days you will be charged for its replacement. A faulty disk is one that gives an 'Abort, Retry, Ignore' error, do not blame every problem you have on faulty disks.

Be polite, if you've been stuck on a problem and haven't got anywhere you may be short tempered, but technical support staff are not councilors, they answer technical questions, not diffuse hot heads.

There are times when written or spoken answers will be short. This is not intended to be an insult, time dictates that replies be kept short.

Believe what you're told. You will not be told that there is a fault in driver A, or software B unless we know it to be true.

Use technical support, but use it wisely - that way software will always be cheap.

Working Title

Office 1

129 Woodstock Rd

Yarnton

Kidlington

Oxon

OX5 1PT

0865 370 175


Negative Numbers

This option determines how negative numbers are displayed.

Normal	Negative numbers are displayed the same as positive numbers.

Show in Red	Negative number are shown in red text  -3.234.

Background in Red	Negative numbers are shown against a red background


Fill Up Down
Fill Up/Down

Introduction

This option extrapolates a series from the entries you supply. With this option you can quickly enter columns of series provided that they follow a pattern.

This option looks for series running down the columns, another option Fill Left/Right looks along the rows for series.

Step- by -Step

You must be in Use Mode.

Highlight the area of the Input Table you wish to extend.

Select Fill Up/Down on the Object Menu.

Patterns Recognised

There are many patterns that CleanSheet recognises, the main one are:

Arithmetical Progressions, such as 10, 20, 30,40...

Geometric Progressions such as 10,100,1000,10000...

Sequences of dates, e.g., \1st Feb 92, \28th Feb 92, \27th March 92, are dates every 27 days

Days of the Month, e.g., \16th Feb 92,  \16th March 92, \16th April 92 are dates on the same day on the month for consecutive months.

Days of the Weeks, e.g., \11th Jun 92, \9th Jul 92, \3rd Aug 92 are all dates representing the second Thursday in every month.

Also different objects can form patterns, for example 1+1i , 2+2i, 3+3i is an arithmetic series, but using complex numbers instead of real numbers.

Example

Notice that only the selected area is affected. In this example, the first column was recognised as the last day of each month and the second column only has one entry which is copied to fill the table.


Fill Left Right
Fill Up/Down

Introduction

This option extrapolates a series from the entries you supply. With this option you can quickly enter columns of series provided that they follow a pattern.

This option looks for series running along the row, another option Fill Up/Down looks down the columns for series.

Step- by -Step

You must be in Use Mode.

Highlight the area of the Input Table you wish to extend.

Select Fill Left/Right on the Object Menu.

Patterns Recognised

There are many patterns that CleanSheet recognises, the main one are:

Arithmetical Progressions, such as 10, 20, 30,40...

Geometric Progressions such as 10,100,1000,10000...

Sequences of dates, e.g., \1st Feb 92, \28th Feb 92, \27th March 92, are dates every 27 days

Days of the Month, e.g., \16th Feb 92,  \16th March 92, \16th April 92 are dates on the same day on the month for consecutive months.

Days of the Weeks, e.g., \11th Jun 92, \9th Jul 92, \3rd Aug 92 are all dates representing the second Thursday in every month.

Also different objects can form patterns, for example 1+1i , 2+2i, 3+3i is an arithmetic series, but using complex numbers instead of real numbers.

Example

Notice that only the selected area is affected. In this example, the first row contained a progression of complex number where each one was -2i multiplied by the previous one. The second row contained only 1 item, so it was repeated.


Pallette of Objects
Pallette

Introduction

The object pallette contains all the available objects within CleanSheet, each icon represents one object and as you move the mouse over the object its name is displayed on the status line.

If the pallette window is too small to display all the objects, a scroll bar is shown on its right edge.

Customising the Pallette

To change the order that the icons appear in, drag one icon over another and the icons will exchange places. Using this mechanism you can arrange the pallette however you wish.

The style and position of the pallette window are set by the Pallette option on the Settings menu, this allows you to place the pallette along the left edge, top edge or as a free standing window.

Placing an Object onto the Sheet

To place an object from the pallette onto the sheet, drag it over the sheet window and drop it.

If the object is a calculation object (i.e. one that can have inputs and outputs) you can drop the object over a pipe, the pipe will be broken and the object linked in automatically.

When you drop an object onto a sheet, the position of the mouse normally represents the centre of the object. However if CleanSheet can avoid overlapping objects by moving the centre slightly, it will do so.

Input Objects

Objects in this section input data from the user into the sheet, click on any icon you want further help with.

 Input Table

 Object Input Box

 Text Box (Input)

 Button Group

 Slider Input

 Tumbler

 Density Graph (Input)

 Polar Graph (Input)

 XY Scatter Input

 Random Generator

Output Objects

Objects in this group output data from the sheet.

 Output Table

 Hard Copy Object

 Filing Clerk

 Line/Column/Area Graph

 Density Graph (Output)

 Pie Chart

 Segment Chart

 Line/Bar/Area Graph

 Polar Graph (Output)

 XY Scatter Graph

 3D Graph

Calculation

Objects in this group perform calculations or manipulations of data.

 Calculator Object

 Cog Calculation

 Summation

 Array Dissector

 Overlay Object

 Computer Object

 Sum Product

 Product

 Savings and Loans

 Toolbox - General

 Toolbox - Financial

Toolbox - Statistical

 Transpose Object

 XY Scatter (Calculation)

 Polar Graph (Calculation)

 Inverter

 Chi-Square Object

 Converter

 Curve Fit Object

 Evaluator Object

Database

Objects in this group are classed as Database object, don't let this restrict you - these objects can just as easily be used in a calculation.

 Database Filter

 Database Sort

 Database Merge

 Lookup Object

 Database Splicer

 Database Extractor

 Database Chopper

 Counter

 Database Comparator

 Database Trimmer

Administration

This group contains objects that administer to the sheet, controlling the flow of data.

 AB to C Switch

 C to AB Switch

 Junction Object

 Switch

 Announcer Object

 Reporter Object

 Solution Search


Button Bar

Introduction

The button bar consists of 4 sections, the layer, sheet mode, calculation mode, and cancel/accept buttons for the edit field.

Layer

Every sheet consists of 100 layers laid one on top of the other. Layer 0 is the top layer, layer 99 is the deepest layer. You can view several layers at once by setting the View Depth on the Sheet View dialogue.

Decreases the layer being displayed by the top sheet window. You can hold down this button to decrease layers continuously.

Increases the layer being displayed by the top sheet window.

Sheet Mode

There are two modes in CleanSheet:

Edit Mode is for editing the layout of the sheet and the pipes connecting objects together.

Use Mode is for calculating and altering the data in the sheet.

Calculation Mode

These two buttons cover how a sheet is recalculated. Note that a sheet is only ever calculated in Use Mode.

With Automatic Recalculation Enabled, the sheet is recalculated whenever a change is made (for example, entering a number in a table).

With Automatic Recalculation Off, the sheet is only recalculated when the Manual Recalculation button is depressed.

Manual Recalculation - recalculates the sheet.

Cancel & Accept

When you have entered or edited text in the edit field these buttons accept and reject the changes.

Cancel the changes, this button can also abort linking a data pipe (See Pipes).

Accept the changes, you can still undo the change with the Undo option on the Edit menu.


Pipes

Introduction

A sheet is a collection of objects linked by pipes, the pipes carry the data between objects and when CleanSheet recalculates a sheet, it is the pipes that are recalculated, not the objects.

Editing and positioning of pipes is only possible in Edit Mode.

Pipe Connections

The pipes join onto the frames around the object at special points called inlets and outlets. Different objects have different inlets and outlets, these are explained fully under the topics covering each object, but there are some basic rules:

 Outlets are always square, when you take a pipe off an outlet, an arrowhead is drawn on the end of the pipe to remind you of the direction of data flow.

 Inlets are always round, when you connect a pipe to an inlet, the pipe is drawn without an arrowhead, this is the tail of the pipe, the data flows away from this end into the inlet.

Pipes always join one outlet to one inlet, any attempt to join inlets to inlets or outlets to outlets is blocked - the pipe simply will not catch.

Linking a Pipe

To connect a pipe:

Click on an outlet or inlet with the mouse and release the mouse button.

A pipe connection will begin.

As you move the mouse around, the pipe will be adjusted - the end of the pipe is attached to the mouse.

If you want to pin down the pipe, click and release the mouse button, now the pipe will be adjusted from the pinned point, this is useful for routing pipes around objects.

To finish the pipe, click on a suitable inlet or outlet. The pipe will now link the objects together.

To cancel the pipe, double click with the mouse, or click the Cancel button on the Button bar.

Linking Long Distances

If the object you want to link to is not visible, there are several things you can do to connect the pipe to it.

Scrolling	Click with the mouse button to start a pipe, don't release the mouse button. Now when you move off the edge of the window it will scroll.

Panes	Each window consists of up to 4 panes (See Window Management), these panes can be scrolled independently, so you can arrange 2 panes, one for the source object, one for the destination object.
Now you can click (and release) to start a pipe, move to the next pane and click to finish it.

Multiple Windows	There can be up to 8 different view windows onto the same sheet (See Window Management). You can set one view window to the view the source object and one to view the destination object. To link the two, simply click (and release) on the outlet and click on the inlet, the two are now joined.

Linking Different Layers

If the source and destination objects are not on the same layers, there are two approaches you can use to link them:

One Window	Click (and release) on the inlet or outlet of one of the objects. Now go up to the layer arrows and click on the up or down arrow to change layers.
Finally, click with the mouse on the second object's frame.

Two Windows	Set up two different view windows onto the same sheet, one viewing the source layer and one viewing the destination layer.
Click (and release) on the source outlet and then click on the destination inlet.

When a pipe is linked across several layers, it is only displayed on the deepest layer it attaches to.

Breaking Pipes

To break a pipe joining two object together:

Hold down the control key and click on the outlet or inlet the pipe is connected to. The pipe will break and the end of the pipe will attach to the mouse cursor.

Click on the pipe along its length (not over the inlets or outlets). Move the mouse while still holder the mouse button down. The pipe will break, the end nearest the mouse will attached to the mouse cursor.

You can now reposition the pipe or attach it to a different object. If you want to delete the pipe completely - double click with the mouse, or click the Cancel button on the Button bar.

Viewing the Contents of a Pipe

To view the content of a pipe, double click on it (not over the outlets or inlets) - a view window will open showing the contents of the pipe. You can open as many view windows as you want, but only one per pipe.

These views are updated every time the pipe is recalculated, so if you want to see how a sheet is being evaluated, you can view the flow of data through the pipes using these windows.

Colouring Pipes

The pipes are available in a range of styles, set by the Pipe Options dialogue. But there is more to a pipe than its display style - you can colour pipes to trace faults in your sheet. The main options are Colouring of Circular References and Colour by Content. See the Pipe Options dialogue for more details on these.


Edit Mode, Explained
Edit Mode

Introduction

CleanSheet has two modes, Use Mode and Edit Mode, in Edit mode the layout of the objects on the sheet, their style and connections are edited.

Selecting this button on the button bar switches to Edit mode. Alternatively you can select Edit Sheet Mode on the Settings menu.

Actions

Clicking the mouse on an object in this mode, moves the whole object around the sheet.

Some objects (the Tumbler Object, Text Box, Object Input Box, Slider, Input Table and Output Table) can be resized in this mode, this is explained in more detail under the relevant object topic.

Several objects can be selected at once.

Pipes can be edited and objects linked by connecting pipes.

All frames and all pipes are visible in Edit Mode.

Clipboard Actions

Cut - Cuts out the selected objects to the clipboard, deleting them from the sheet.

Copy - Copies the selected object, or objects to the clipboard.

Paste - Pastes the objects in the clipboard onto the sheet.

Clear  - Deletes the selected objects from the sheet without affecting the clipboard.

Selecting Single Objects

Click on the object, or click on the frame of the object (avoiding the Outlets and Inlets which will start a pipe).

Selecting Multiple Objects

There are several ways of selecting multiple objects:

Click on each object one-by-one, holding down the Shift Key.

Click outside any objects on the backdrop and drag a banding box around the objects to select.

Use the Select Special to select multiple objects by their type, name, or tags.


Use Mode, Explained
Use Mode

Introduction

CleanSheet has two modes, Edit Mode and Use Mode, in Use Mode, the sheet can be calculated, the data in the objects changed, and any mouse action or keyboard actions specific to that object come into use.

Selecting this button on the button bar switches to Use Mode, alternatively you can uncheck the Edit Sheet option on the Settings menu.

Actions

Clicking the mouse on an object in this mode, sends the mouse action to the object, (for example on an Input Table, it positions the insert point), each mouse action is explained in the topic covering each object.

Keys you press, and text you type in is sent to the object (for example cursor up on the Input Table moves the insert point up one line).

Only one object can be selected at any one time, that object has input focus - keys pressed will be sent to the selected object.

Pipes cannot be edited, deleted or added in this mode.

If you have elected to Hide Pipes, Frames or Whole Objects (see Object Attributes), then this is only done in Use Mode.

Clipboard Actions

The clipboard is handled by the object themselves, each action they perform is explained in the topic covering that object.

Selecting an Objects

Click on the object, or click on the frame of the object.

Press Tab, objects that can receive keyboard or mouse actions in Use Mode can be selected using the Tab key, only objects currently visible will be selected and you can cycle backwards through the list with Shift Tab.


 The Tab key sometimes looks like this.


  Hold down shift key and press tab.


General Mathematical Operators, Listed
General Mathematical Operators

This is a full list of the operators available within the expression evaluator of CleanSheet. To obtain information on any item, click on it.

Assignment to Variables

#~=	^=	#&=	#|=	#<=	#>=

+=	-=	*=	/=	?=	:=

Grouping Conditions

&	|

Bitwise Operators

#~	#>	#<	#&	#|

Simple Arithmetic

* Multiply

+Add

/Divide

?Modulus

^Raise

-Subtract

%Percentage

Vague Logic Operators

>=<	>==<	>===<	>====<	Vague Equals

<=>	<==>	<===>	<====>	Vague Not Equals

>>>>>	>>>>	>>>	>>	Vague Greater Than

<<<<<	<<<<	<<<	<<	Vague Less Than

Comparison Operators

=	>=	<=	>	<	!=	!

Constants

true	Boolean True

false	Boolean False

null	Null

identity2	2x2 Identity Matrix

identity3	3x3 Identity Matrix

Conversion Format Strings

generalform	currencyform	commacurrencyform	commaintcurrencyform

scientificform	percentform	percentintform	ledgerform

ledgerintform	fractionform	signedform	integerform

signedintform	time24form	time12form	shorttime24form

shorttime12form	formaldateform	fulldateform	shortdateform

dateform	complexform	complexintform	complexfixform

Currency Symbols

£	$	dm	ff	lire	pts

yen	sf	bf	dfl

These are all documented under Currency Symbols

See Also

General Functions, Listed

Geometric Functions, Listed

Trigonometric Functions, Listed

Array Manipulation Functions, Listed

Financial Functions, Listed

Statistical Functions, Listed


General Functions, Listed
General Functions

addsecs	Add seconds

angle	Angle between two vectors

ariseries	Arithmetic Series

clean	Remove bad characters from strings

compare	Compare two objects (Vague Compare)

cross	Vector Cross Product

days360	Difference between two dates

degtorad	Degrees to Radian

dot	Vector Dot Product

exp	e^x

extrapolate	Create series by example

geoseries	Geometric Series

int	Integerise

invert	Invert an object

ln	Naperian Log

log	Log to base n

log10	Log to base 10

lower	Lowercase a string

mag	Magnitude of Object

make	Make one object type into another

makearray	Make an array

matmul	Matrix Multiplication

now	The present time

pi	PI 3.141...

proper	Fix a string/Date/Time

ptoc	Polar to Complex

ptor	Polar to Rectangular

radtodeg	Radians to Degrees

rand	Random Number

round	Round to decimal places

rtop	Rectangular to Polar

sign	Sign of number

size	Size of an object

sqrt	Square Root

today	The present date

trim	Trim excess spaces from strings

type	Type of an object

upper	Raise case of a string

weekday	Calculate weekday from date

See Also

General Mathematical Operators, Listed

Geometric Functions, Listed

Trigonometric Functions, Listed

Array Manipulation Functions, Listed

Financial Functions, Listed

Statistical Functions, Listed


Geometric Functions, Listed
Geometric Functions

areapoly	Area of polygon

areaellipse	Area of ellipse

arearect	Area of rectangle

areapie	Area of pie segment

inpolygon	Inside Polygon

inellipse	Inside Ellipse

inrect	Inside Rectangle

inpie	Inside Pie segment

See Also

General Mathematical Operators, Listed

General Functions, Listed

Trigonometric Functions, Listed

Array Manipulation Functions, Listed

Financial Functions, Listed

Statistical Functions, Listed


Trigometric/Hyperbolic Functions, Listed
Trigonometric/Hyperbolic Functions

acos	Inverse Cosine

acosec	Inverse CoSecant

acosh	Inverse Hyperbolic Cosine

acot	Inverse Cotangent

asec	Inverse Secant

asin	Inverse Sin

asinh	Inverse Hyperbolic Sin

atan	Inverse Tangent

atan2	Inverse Tangent (from quotient)

atanh	Inverse Hyperbolic Tangent

cos	Cosine of angle

cosec	Cosecant of angle

cosh	Hyperbolic CoSine

cot	Cotangent of angle

sec	Secant of angle

sin	Sin of angle

sinh	Hyperbolic Sin

tan	Tangent of angle

tanh	Hyperbolic Tangent

See Also

General Mathematical Operators, Listed

General Functions, Listed

Geometric Functions, Listed

Array Manipulation Functions, Listed

Financial Functions, Listed

Statistical Functions, Listed


Array Manipulation Functions, Listed
Array Manipulation

downsort1	Sort into descending order dimension 1

downsort2	Sort into descending order dimensions 2

extract	Extract subset from array

farsort1	Sort by furthest, dimension 1

farsort2	Sort by furthest, dimensions 2

farthest	Find worst Match

fullsearch	Search all array

fullvaguesearch	Vague Search all of an Array

furthest	Find worst Match

insdim1	Insert into Dimension 1

insdim2	Insert into Dimension 2

nearest	Find nearest Match

nearsort1	Sort by nearest, dimension 1

nearsort2	Sort by nearest, dimensions 2

remove	Remove subset from array

search	Search an array

transpose	Transpose an array

upsort1	Sort dimension 1 into Ascending order

upsort2	Sort into ascending order dimension 2

vaguesearch	Vague Search an Array

See Also

General Mathematical Operators, Listed

General Functions, Listed

Geometric Functions, Listed

Trigonometric Functions, Listed

Financial Functions, Listed

Statistical Functions, Listed


Financial Functions, Listed
Financial Functions

ddb	Double-Declining Depreciation

fv	Future Value

ipmt	Interest Payment

irr	Internal Rate of Return

nper	Number of Periods

npv	Net Present Value

pmt	Payment

ppmt	Principal Payment

pv	Present Value

rate	Rate of interest

sal	Savings and Loans

sln	Straight-Line Depreciation

syd	Sum-Years Digits depreciation

vdb	Partial Period Depreciation

See Also

General Mathematical Operators, Listed

General Functions, Listed

Geometric Functions, Listed

Trigonometric Functions, Listed

Array Manipulation Functions, Listed

Statistical Functions, Listed


Statistical Functions, Listed
Statistical Functions

fitline	Fit a line to data

chitest	Chi-Square test

combinations	Combinations r from n

count	Count of numbers

eval	Evaluate function

fitexp	Fit an exponential curve to data

fitpoly	Fit a polynomial to data

fitsqr	Fit a x-square curve to data

flatten	Flatten Array to 1 dimensional

integrate	Integrate Equation

max	Maximum

mean	Average

median	Median value

min	Minimum

sparsefact	Spare Factorial (Permutations)

stdev	Standard Deviation

stdevp	Standard Deviation of Population

sum	Sum

sumsqr	Sum of squares

var	Variance

varp	Variance of Population

Normal Distribution	probnormal	densnormal	threshnormal

Binomial Distribution	probbinomial	densbinomial	threshbinomial

Poisson Distribution	probpoisson	denspoisson	threshpoisson

Exponential Distribution	probexp	densexp	threshexp

Rectangular Distribution	probrect	densrect	threshrect

HyperGeometric Distribution	probhypergeo	denshypergeo	threshhypergeo

Chi-Square Distribution	denschisqr	probchisqr	threshchisqr

F Distribution	densf	probf	threshf

Gamma Distribution	densgamma	probgamma	threshgamma

T Distribution	denst	probt	thresht

See Also

General Mathematical Operators, Listed

General Functions, Listed

Geometric Functions, Listed

Trigonometric Functions, Listed

Array Manipulation Functions, Listed

Financial Functions, Listed


Cesk Programming Language, Introduction

The programming language within CleanSheet is called Cesk (pronounced C-eSk), it is very similar to the programming language 'C' in its syntax and therefore where the syntax differs, this is noted.

The programming language is split into two distinct parts

The expression evaluator. This is available within most of the calculation objects, and is responsible for evaluating equations and functions.

The Structure Command. These are the main programming framework, the user functions, the program flow and loop constructs, are all part of this section. These statements are only available within the Computer Object.

A full list of the functions and operators available within the expression evaluator is given in the topics listed below.

General Functions, Listed

Geometric Functions, Listed

Trigonometric Functions, Listed

Array Manipulation Functions, Listed

Financial Functions, Listed

Statistical Functions, Listed

General Mathematical Operators, Listed

The topics covering the different aspects of programming are:

CeSk- General Information

CeSk - IF Statement

CeSk - WHILE Statement

CeSk - DO Statement

CeSk - FOR Statement

CeSk - SWITCH Statement

CeSk - Break Statement

CeSk - Break2, Break3, Break4, Break5 Statements

CeSk - CONTINUE Statement

CeSk - Break2Continue Statement

CeSk - RETURN Statement

CeSk - User Defined Functions

CeSk - Variables and Their Scope

CeSk - Program Example

There is considerable blurring within the functions of CleanSheet. You may find functions explained in terms of a database, that you can use in a calculation or calculating functions that can be used for programming use. It is important that you understand that each function was written with this in mind, do not avoid sections of the program simply because you think they're not relevant to you.


Cesk - General Information

Cesk is not case sensitive, commands can be entered in upper or lower case, e.g., MakeArray is the same as makearray.

To separate commands a semi-colon is used. e.g. a:=3; b:=4; c:=5 ;

Sections of commands are usually specified using curly bracket to group the commands together, e.g., IF (a=2) { a:=3; b:=5; };

Comment can be placed anywhere by enclosing them in /* and */ , e.g. IF (a=2 /* if the count has reached 2 */)  { a:=3; b:=5; };

The main function within a CeSk program is called main{}, when a program is run the function main{} is called regardless of whether there are any functions above it.

Main is a function, the value it returns is the return from the whole program. Similarly the parameters passed to main{} are the parameters passed to the whole program.

A typical program that adds Input A to input B and returns the result would look like this.

main {

return (a+b)

};

C [image]  Notice that the variables are already stored in a,b,c... which correspond to the inputs a,b,c... of the Computer Object. You should not declare the variables as you would in C.


Cesk, IF Statement
CeSk,  IF (expression) ...ELSE...

The IF..ELSE statements switches the flow of execution of a program depending on a TRUE/FALSE test.

if (expression)

   trueaction;

else

   falseaction;

 The (expression) must be bracketed with ( ).

The value of (expression),  is evaluated, and if found to be TRUE (any non-zero result) then the statements represented by 'trueaction' are executed, otherwise the (optional) statements represented by 'falseaction' are executed.

Note that (expression) can consist of any test that returns a TRUE or FALSE, zero or non-zero, e.g. a Boolean, a number, relative comparison of strings, etc.  Where the test involves the use of floating point values, which cannot always be represented exactly, then CleanSheet will regard any value between -1e-15 and +1e-15 as being zero (or FALSE).

If there is no action to be taken for a FALSE result, then the ELSE clause may be skipped.

if (expression)

trueaction;

Should you wish a group of statements to be run for 'trueaction' or 'falseaction', then the statements should be grouped using { } brackets.

For example:

if (abc) am := 1; else pm := 1;

If the variable 'abc' is non-zero (or TRUE), then the variable 'am' is set to the value 1, otherwise the variable 'pm' is set to 1.

if (abc > 2) {am := 1; hm -= 12;} else {pm := 1; hm += 12;};

If the variable 'abc' is greater than 2, then the variable 'am' is set to 1, and the variable 'hm' has 12 subtracted from it current value. If 'abc' is less than or equal to 2, then the variable 'pm' is set to 1 and the variable 'hm' has 12 added to its current value.

Note that the first set of curly brackets do not end in a semi-colon, but the second set does, to terminate the IF command.  If there were no ELSE group then the semi-colon would appear after the first closing curly bracket.

C [image] IF statements can be nested, but when this is done the statements to be run as trueaction or falseaction must be enclosed within { }'s, e.g.

if (abc > 2)	<--------- Start of 1st level IF

   {	<--------- Start of trueaction for 1st level IF

     if (pm) {	<--------- Start of 2nd level IF

        kom := 1;	<--------- Trueaction for 2nd IF/end of 2nd level IF

    }	<--------- End of trueaction for 1st level IF

else

    {	<--------- Start of falseaction for 1st level IF

      if (xyz) {	<--------- Start of 2nd level IF

         tim:= "Hello";	<--------- Trueaction for 2nd level IF

      };	<--------- end of 2nd level IF

    };	<--------- End of falseaction for 1st level IF


CeSk - WHILE statement
WHILE (expression) action;

WHILE evaluates the expression and if TRUE, executes the action. It then repeats the process, evaluation the expression and if TRUE, executing the action. Finally stopping when (expression) evaluates to FALSE.

(expression) must be given within the ( ) brackets, and if several actions are required as part of the loop they should be enclosed within { } brackets.

For example:

while (abc > 2) abc -= 1;

While the value held in variable 'abc' is greater than 2, subtract 1 from 'abc', loop and then retest.

while (abc > 2) {abc -= 1; kom[abc] := 3;};

While the value of 'abc' is greater than 2, subtract 1 from 'abc', and then use the current value of 'abce' to index into the list 'kom[ ]', setting the element to 3. Return to the start of the loop and retest. Note carefully the semi-colon after the closing bracket, used to terminate the WHILE statement.

Contrast the while loop with the do loop. The while loop test the condition before the action is executed, the do loop tests the condition after the action is executed. Hence the do loop always executes the action at least once, but the while loop may never execute the action at all.

See Also CeSk - Do Statements


CeSk - DO Statement
DO action WHILE (expression)

The DO ... WHILE is a variant of the WHILE loop. It differs in that the actions are always executed at least once, since the test does not occur until the end of the loop.

Contrast this with the normal WHILE loop, which tests at the top of the loop and hence the action may never be performed.

For example:

do abc -= 1; while (abc > 2);

Subtract one from 'abc'. If 'abc' is greater than 2, repeat.

do {abc -= 1; kom[abc] := 3;} while (abc > 2);

Subtract 1 from 'abc'. Use the current value of 'abc' to set list element 'kom[abc]' to 3. If 'abc' is greater than 2, repeat.

 The expression used to test if the loop continues MUST be enclosed in brackets ( ).

 The action should always be enclosed in curly brackets { }.


CeSk - FOR Statement
FOR (initaction; conditional; postaction;) ...

The FOR loop is another form of looping construct, generally used where the flow of a WHILE or DO...WHILE loop would obscure the logic of the program.

It first evaluates 'initaction', and then performs the 'conditional' test. If the 'conditional' test returns a FALSE result, then the loop is skipped or terminates; if the test returns a TRUE result, then the main body of the loop is run. After the main body of the loop has run, 'postaction' is then evaluated.

This is equivalent to the construct

initaction;

while (conditional) {

mainaction;

   	postaction;

};

Whether you opt for this style of loop, or for a For loop depends on the situation.

As an example:

for (x := 0; x < 10; x += 1;) abd[2*x] := 3;

Set x to 0. If x is less than 10, set abd[2*x] to 3. Add one to x, loop and retest x.

which as a WHILE loop would be

x := 0; while (x < 10) {abd[2*x] := 3; x += 1;};

This is different from the C programming language in that a semicolon must be placed after the post action:

for (x := 0; x < 10; x += 1;)	/* semi-colon corrects */

for (x := 0; x < 10; x += 1)	/* semi-colon missing */


CeSk - SWITCH Statement
SWITCH (expression)

The SWITCH statement allows a multi-way choice to be made, without requiring several levels of complex IF ... ELSE ... statements. It takes the form

switch (expression)

             {

               case (value1): 	action1;  break;

               case (value2): 	action2;  break;

                .

                .

               default:	defaultaction;

              };

The value of (expression) is calculated, and then compared in turn to each of the values given in the case selections; If a match is found, then the actions specified for that case are executed. A default selection can be used as a catch-all, if none of the case tests are explicitly matched.

Notice a case construct closeup  case (10) :

The case ends in a colon, which tells CeSk where the next statement begins.

Note that each of the values attached to a case must be enclosed within ( )  brackets - this is different from the C convention, which does not require the ( ).

If you wish to use several statements for a particular matching case, then the statements do not need to be enclosed within { } brackets.

The case tests can be in any order. Unless you use a BREAK statement to exit the switch, execution will continue through any CASE statements below the matching one.

For example, assuming the variable abc currently has the value of 10, then

switch (abc - 2) {

case (3) :

default:	abd := 3;

case (10):	mik := 5;

};

Then because the expression (abc - 2) does not have an explicitly matching case value of 8, the default selection is taken, setting abd to the value 3. Since there is no BREAK terminating this group, the code then falls through to the statements associated with the case(10) test, setting the variable 'mik' to 5. Note that 'abd' will also be set if abc has a value of 5, since the case(3) match will fall through to the default code; only if abc has the value 12 will abd not have a value assigned.

The switch statement is exactly identical to groups of IF statements.

Switch (abc) {

case (1) : a:=1; break;

case (2): b:=1; break;

case (3) c:=1; break;

default: d:=1; break;

};

Is equivalent to:

If (abc=1) a:=1;

else {

if (abc=2) b:=1;

else {

if (abc=3) c:=1;

else {

d:=1;

};

};

};

Notice that the equivalent IF statements are nested in curly brackets. CeSk insists on nesting of brackets when IF's are nested.


CeSk - BREAK Statement
BREAK

BREAK is used to step up from the deepest WHILE, DO, FOR or SWITCH construct by one level. It will not break out of a series of IF statements. The loop or switch command is terminated, and the code is continued from just after the closing bracket for the construct. For example, using a switch statement:

abc:=8;

switch (abc - 2)  {

case (3):

default:	abd := 3;

break;

case (10):	mink := 5;

};

Here the break statement, breaks out of the Switch construct, after executing abd:=3;

a:=0; c:=0;

while (a<10) {

c+=a;

if (c>5) break;

};

d:=1;

Here the break statement breaks out of the while loop when c is greater than 5 and execution continues at the line d:=1;


CeSk - Break2, Break3... Statement
BREAK2, BREAK3, BREAK4, BREAK5

The above statements all work in a similar manner to BREAK, except that they will break out of the 2, 3, 4 or 5 deepest levels of WHILE, DO, FOR or SWITCH constructs, i.e.

while (abc > 3) {

  mik := 5;

while (mik != 0) {

if (mik = 3 & abc = 1) break2;

mik -= 1;

};

  	abc -= 1;

};

/* when mik is 3 and abc is 1, break2 causes execution to continue here */

When mik equals 3 and abc equals 1, then the Break2 will terminate both WHILE loops.


CeSk - CONTINUE Statement
CONTINUE

The CONTINUE statement continues execution at the end of a WHILE, DO or FOR loop, skipping intermediate statements.

Cnt := 0

while (abc > 10) {

 	abc -= 1;

if (abc > 6) continue;

Cnt += 1;

};

When abc is greater than 6, the statement Cnt+=1; is skipped and the loop continues onto its next iteration.


CeSk - BREAKCONTINUE Statement
BREAKCONTINUE

Breaks out of the innermost loop and continues with the next iteration of the next outer loop. As its name implies, it performs the equivalent of a BREAK followed by an immediate CONTINUE.

You may wonder why it is different from simply putting Break; Continue; within a program. If you were to put two statements Break; then follow it with Continue; the continue would never be executed. Break breaks out of the loop.


CeSk - BREAK2CONTINUE
BREAK2CONTINUE

This statement breaks out of the two deepest loops and continues on the next outer loop.

In effect it executes two Break commands and follows it with a Continue command.


CeSk - RETURN Statement
RETURN

Return is used to transfer control back from a function to the function's caller - it indicates an unconditional exit from the function.

It can just return to its caller, or return a result for use of the caller e.g.

return;	just returns

return {abc,"Error"};	returns an array of 2 values, the contents of variable 'abc', and the string "Error".

If this command is used within the main{} function, then the program stops and the return value is the result that the Computer Object produces as a result.


CeSk - User Functions
User Functions.

Functions may be used to encapsulate commonly used sequences of code, allowing a simpler structure and easier flow of logic for the whole program.

They are defined by simply following a (non-reserved) name with { }'s, which enclose the code for the function, i.e.

main { };	- is just an empty function called 'main'

myfunc { A -= 1; };	- is a function called 'myfunc', that simply subtracts one from the value of A. Note that of itself, this is pretty useless; it takes nothing and returns nothing.

add3 { return(ip+3);};	- is a function called 'add3', which takes a single passed value (see later) of whatever object type, adds three, and returns the result. Hence a numeric will return its current value + 3, a date object the date 3 days beyond the passed date, and so on.

 The order the functions are placed within a file is unimportant.

Functions may call themselves recursively, or other functions as required; the nesting limit for function calls is dependent only on the available stack space within the computer.

Functions can accept only 1 argument and return 1 result. This may seem like a serious limitation, but the argument can be an array, and similarly the result can be an array.

Thus an argument list could contain any of the CleanSheet object types, either as single values, lists or arrays of the same object types, or lists or arrays of disparate objects,

e.g. MyFunc {123,"This is a string",{2+3j,4+6i},{{1,1},{2,2}},\26th Jan 62}

calls the function MyFunc with a whole range of different parameters, passed as a single array.

Because a called function may have no idea of what parameters to expect, all of the passed parameters are assigned to a local function variable called 'ip' (short for input) - if the function takes no parameters then ip will contain a null object. Using the above example, ip[0] refers to the value 123, ip[2][1] refers to the complex number 4+6i, and so on. Hence, using the appropriate intrinsic functions, a user function can customise itself to deal with any form or number of passed arguments automatically.

When the function main{} is called, the parameters for a,b,c are placed in variables a,b,c... not in ip. This is different from user defined function.

Notice that the functions are available only within the Computer Object they are defined in. They do not appear outside of that object.


CeSk - Variables and their Scope
Variables and their Scope.

Variables do not have to be explicitly declared - simply assigning a value to a variable name (this is a difference from the programming language C) both creates the variable and assigns the initial value. Within a function, variables that are created are automatic by default i.e. when the function exits, the variable will be destroyed. For example, consider the following functions

MyFunc {

abc += 1;

return(abc);

};

Main{

V1 := MyFunc;

V2 := MyFunc;

};

After the calls in Main{ }, both V1 and V2 would equal 1, since the value of the variable 'abc' in function MyFunc{ } is 'lost' when MyFunc{ } terminates, and thus starts as a Null object - the call the becomes null+1 -> 1, which is the value returned to Main{ }.

Also variables are local within the function, you can use the same variable name in any number of functions and they all refer to different variables.

MyFunc{ abc := 20}

Main{ abc := 100; MyFunc;};

With the function Main, abc has the value 100, while during the call to MyFunc{ }, the scope changes and the local variable abc (of value 20) is relevant within MyFunct. After the call to MyFunct, abc is once again 100;

Normal variables are limited to the function they are used in.

l_ (L underscore)	Variables prefixed with 'l_' are LOCAL, available to the all the functions within a Computer Object. When the object is copied to the clipboard, or the sheet saved, the contents of the variable are saved with it.

ls_ (LS underscore)	Same as L_

los_ (LOS underscore)	Same as L_

lo_ (LO underscore)	Same as L_

g_ (G underscore)	GLOBAL. A variable having GLOBAL scope can be seen by all objects on the sheet, it is also saved with the sheet, but since its not specific to an object, it is not copied when the object is copied to the clipboard.

gs_ (GS underscore)	Same as G_

w_ (W underscore)	WIDE variables have scope that makes them visible to all objects in all loaded sheets (not just the current sheet). WIDE variables are saved with the program and should be used to store options that are program wide.

wp_ (WP underscore)	Same as W_

This is an important system to understand, as its widely used by the objects themselves albeit in an undocumented manner. For example the variable ls_g within a computer object contains an array with 2 elements, the first is the number of input pipes as an integer and the second is the tokenised equation for the program.
It is important that you separate which variable prefixes to use in which circumstance.


CeSk Program Example

The following code is an example of a CleanSheet Program. To see details on any of the operators or functions used, click on the function.

This program finds the highest common denominator out of the values fed into a Computer Object, it is not a very efficient method, but illustrates several useful constructs.

main {

/* group the inputs into a single array */

ip:={a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z};

/* find the smallest input */

result:=0;

for (i:=0@; i<26@; i+=1@;) {

k:=ip[i];

if (k!=null) {	/* is the pipe empty? */

if (result=0) result:=k;

if (k<result) result:=k;

/* if non - integer input, then return error */

if (int(k) !=k) return make {"Input is not an integer.",6};

};

};

/* if there is no suitable input then return an error */

if (result<1) return make {"No HCD Error",6};

do {

for (i:=0@; i<26@; i+=1@;) {

k:=ip[i];	/* get input number i and check its not empty */

if (k != null) {

if (int(k/result)*result != k) break;

};

};

if (i=26@) {	/* all inputs were divisible */

return result;  /* Return result as output */

};

result-=1;	/* try a smaller result */

} while (result>1);

return result;

};


This statement groups the inputs a,b,c...z into a single 1 dimensional array. Doing this enables a FOR loop to step through each input in tern.


Step through the ip array we have constructed, to find the smallest input pipe, this will be our starting point for testing, since there can be no highest common denominator larger than the smallest value.


Extract pipe number i from the array of input pipe data and assign it to the variable k.


If k is Null, then the pipe was empty, and we can ignore any empty pipes.


If Result is zero, then its value is invalid and we can safely overwrite it.


If k is smaller than Result, then update Result. Remember that we are trying to find the smallest input pipe.


If k is not an integer (in other words int(k) is not the same as k), then an input pipe is not integer. Only integers are allowed in highest common denominator calculations.


If Result is still zero, then there were no suitable input pipes to apply a lowest common denominator calculation to.

Notice that make is used here to make a string into an error object and return it as the result. This appears to the rest of the sheet as an error.


Go through all the possible values, starting with Result, and testing Result-1, Result -2... until a value is found that is divisible.


Go through the input pipes to test if they are all divisible by Result.


Get the contents of input pipe i into variable k.


If the pipe contained something then k is not Null.


If dividing the pipes contents by Result does not produce an integer, then break out of the loop. For Highest Common Denominator, all the pipes that contain numbers must be divisible.


If all the pipes were divisible, then the loop must have terminated due to i being 26, hence we have found a result.


Return the result variable as the result of our program.


Subtract 1 from the result, so we can try the next smallest result.


Stop when the result value reaches 1, all integers must be divisible by 1 to produce an integer result, so there is no pointed testing for it.


We have not found a better result, so return the result 1.


Initialise Result to be zero before we search for the smallest input pipe.


Welcome
Welcome to CleanSheet

Introduction

This topic explains only the concept behind CleanSheet, reading it is not essential.

As you have no doubt noticed CleanSheet is not like any other spreadsheet. A traditional spreadsheet is an interactive ledger, with cells that do everything, input, calculation and output. This was fine when spreadsheets were simple, but as more features were added, more menus and options were added. Now each cell has lots of different options and the spreadsheet has no way of telling which are relevant, so it has to present all the options all the time.

Spreadsheet companies have tried to get around this using two methods, firstly they hide the options on short menus (but ultimately you will have to switch on full menus), or they create modal sheets - Macro Sheets, Spreadsheets, Chart Sheets and so on, limiting the range of each individual sheet to simplify them.

To compete in this market we had to produce a much more powerful spreadsheet, with a full range of features, Solvers, Programmability, 3D Graphs, and so on. But to do this on a traditional spreadsheet would have been impractical. Instead CleanSheet separates out the functions of Input, Calculation and Output into different objects. Each object is tailored to its particular function, so there are no tradeoffs.

The objects are linked by data pipes, visible lines on screen. This gave us another way of improving on the traditional sheet. Data pipes allow you to see how objects interact. If there is a circular reference, CleanSheet can highlight it by colouring the data pipes - you don't have to trace the circular reference - you can see it.

When an object is selected, the menus relevant to it are displayed on the Object menu. There simply isn't a point in displaying irrelevant menu items, and so, even though CleanSheet would need well over a hundred menus to handle all its function, you never have to face all of these menus at once.

Liberation

Once free from limitations imposed by history, a whole range of questions can be addressed:

Why is the only input into a sheet a number entered into a cell? Entering numbers in a cell is not very interactive and gives little feedback. Once you have separated Input, output and calculation, there is no reason at all why you can't have other input devices. CleanSheet has a whole range of them.

The only outputs are numbers or graphs? Again, CleanSheet offers printer and file outputs as well as a wider range of graphs. There simply is not penalty to adding objects other than the space taken by the icon in the pallette window and some extra disk space for the code.

Why are graphs only for output anyway? If your sales over a year consists of a flat line with two peaks at Easter and Christmas, why can't you use that graph as a function - why approximate it? CleanSheet has Calculation XY Scatter and Calculation Polar Graphs  - the graph is the function. In the same vain, there are Input versions of these graphs.

Why 2 dimensional data? Data is 2 dimensional because the sheet is two dimensional, to step into three or more dimensions takes a bit more planning. CleanSheet tackles this by using array notation, the first two dimensions can be displayed as a table, further dimensions (up to 10 dimensional data can be handled) are displayed using array notation.

Why are the database functions separate? Database functions were added to the feature list later and hence in a traditional spreadsheet you can see the join. In CleanSheet, the database objects are just calculation objects that are slightly more oriented to handling data - you can't see the seam because there isn't one.

Why handle only strict mathematical forms? If you think about it, the ledger side of a spreadsheet handles strict mathematical forms, everything is equations and numbers, everything is rigid quantities. On the other hand the database handle vague quantities, 'find a name that approximately matches this search pattern', and so on. CleanSheet was always going to have a database, so the techniques for the database were defined right from the start. It contains a form of fuzzy logic, called Vague Operators. These appear all the way through the sheet, they can be used in calculations to find the nearest acceptable price, or in databases to find the nearest matching name - no seam.

Disadvantages

There is inevitably a big disadvantage to this sheet - it's unfamiliar. If CleanSheet was just another spreadsheet, you could sit down, and use it straight away. It isn't and you can't. You have to learn a few things first, and for this purpose there is a topic listed in the contents called Getting Started Quickly which lists the minimum topics you need to read to get started.

Welcome to CleanSheet.


Quick Start
Getting Started Quickly

To create and use simple sheets you need to be familiar with the following topics:

Data Types

Edit Mode and Use Mode

The Button Bar

The Menus

Pipes

Placing Objects onto the Sheet

Function Arguments

Cesk - General Information

And the following objects (click on the icon to read about them):

 Input Table

 Object Input Box

 Output Table

 Calculator Object

 Cog Calculation

 Array Dissector

 Overlay Object

Once you have learned these, you can create a lot of standard spreadsheets.

You may be tempted to try and convert a standard spreadsheet to a CleanSheet worksheet. This is extremely hard, the concepts you use with CleanSheet are completely different from the concepts on a traditional spreadsheet. You must understand the problem that the old spreadsheet tackled and apply the new tools to the old problem - once you can do this you can make the necessary leap in understanding - mechanical conversion of sheets does not work.


Placing Objects onto a Sheet
Placing an Object onto the Sheet

To place an object from the pallette onto the sheet, drag it over the sheet window and drop it.

If the object is a calculation object (i.e. one that can have inputs and outputs) you can drop the object over a pipe, the pipe will be broken and the object linked in automatically.

When you drop an object onto a sheet, the position of the mouse normally represents the centre of the object. However if CleanSheet can avoid overlapping objects by moving the centre slightly, it will do so.


Conventions

The following conventions are used in the documentation of CleanSheet.

NULL	The null data object

Integer	Integer Number Objects

Float	Floating Point, Single Precision Objects

Double	Double Precision Floating Point Objects

String	Strings of Characters i.e. Text

Error	Object Defining Text of an Error

Date	A Calender Date

Time	A Chronological time Object

Complex	A Complex Number (Real+Imaginary)

Equation	An Equation (which can be evaluated)

Array	A Group of Other Objects.

The basic object types are supplemented by other words in this text.

All	All objects in the above list.

Numerics	Integers, Floats, Doubles and in addition Time and Date objects are converted into numerical forms, when a numeric type is required.

Icon Conventions

This Icon emphasizes features which stand out - so called Star Features, or Power Features.

This Icon is used to highlight examples of what not to do, or examples of bad syntax within a function.

This Icon is used to emphasize good examples of the use of a function or object. It is also used for paragraphs that give correct ways to do something.

A paragraph highlighted with a bulb indicates an idea or suggestion, usually pointing out how a feature could be used.

Used to point out paragraphs containing notes. Paragraphs highlighted by a pencil should not be skipped as they contain important information.

A paragraph highlighted like this indicates a key paragraph which will give you an important insite into the object or function. In effect it unlocks a problem.


- Subtraction Operator
- Subtraction

The subtraction operator's exact action depends on the objects it operates on, the following is an exact list, this list is similar to addition, but note that subtraction is not commutative, a - b is not the same as b - a, and similarly Date - Number is not the same as Number - Date

For a list of conventions used, see Conventions

Any - Null	Subtraction NULL from an object returns the object unchanged., e.g., 1 - NULL returns 1, "Smith" - NULL returns "Smith"

Integer -  Integer	Subtracting an integer value from an integer returns an integer, e.g. 1@ - 2@ returns -1@

Integer - Float	Subtracting an integer from a single real value, or a single real value from a single real value returns a single real value, e.g. 3@ - 0.142 returns 2.858,  6.234 - 1.766 returns 4.468

Integer - Double	Subtracting an integer, single real, or double real value from a double real value returns a double real value, e.g., 3.141- 3@ returns 0.141.

Time - Numeric	Subtracting a number from a Time object, treats the number as seconds, and adjusts the time accordingly. e.g. 12:15:20 - 80@ return 12:14:00.

Complex - Numeric	Subtracting an integer, single real, double real, time or complex number from a complex number returns a complex number, e.g. 10+2j - 10@ returns 0+2j.

Boolean  - Numeric	 A Boolean object is treated as a number of value 0 (for FALSE) or 1 (for TRUE).

Date - Numeric	Subtracting an integer, single real, or double real value from a date object returns the date object plus the corresponding number of days, e.g. \12th Jan 74 - 3 returns \9th Jan 1974

Date - Date	Subtracting one date from another, returns the number of days between them.

Time - Time	Subtracting one Time from another, returns the number of seconds between them.

Other conversion return errors, for example it is not acceptable to subtract a date from a number, since there is no sensible value such an operator could return.

Array Objects

Subtracting an object from an array object is equivalent to subtracting the object from each of the array elements in turn.  When subtracting two array objects, each dimension is treated separately; for arrays of the same size and dimensions, corresponding values are simply subtracted, element - by - element.  For example

Note that arrays may not just contain numbers, they could hold string elements, or even whole lists or arrays within each element being looked at.


* Multiplication Operator

The exact operation of the multiply operator depends on the objects being multiplied, the list below gives the sensible actions that this operation performs.

For the conventions used in this document see Conventions.

Note that multiplication is commutative (a*b is same as b*a) and hence the order of the objects can be reversed, without affecting the result.

Numeric * Numeric	Multiplying Numeric types returns the product (the multiplication result) as the higher type of object. For example 2@ * 3.2 returns 6.4 as a double precision number. (Integer  * double returns a double because it has more precision and hence is a higher type of object).

Null * Any Object	Multiplying any object, except an error object, by a NULL object will return a NULL object.  An error object will be returned unchanged.

Error * Any Object	Multiplying an Error by anything, return the Error unchanged.

String * Numeric	Multiplying a string object by a value will return the string replicated N times, i.e. "Hello" * 3 returns "HelloHelloHello".

Any Object * Boolean	Multiplying any object by a Boolean object will return the object unchanged if the Boolean value is TRUE, otherwise a NULL object is returned. For example: "abc" * TRUE returns "abc"

Complex * Complex	Multiplying two complex numbers returns the complex product, e.g. (2+3j) * (3+3j) returns -3 + 15j. Note that the preceding expression needs to be bracketed since multiplication has a higher precedence than addition. Without the brackets 2+3j * 3+3j would be evaluated as 2+(3j*3)+3j.

Array * Array	Multiplying arrays, multiplies the corresponding objects in each array.
For example {100,200,300} * {2,3,4} produces an array {200,600,1200}.
Similarly 100*{1,2,3} produces an array {100,200,300}.
Note: To multiply arrays as though they are matrices use the function Matmul.

Example

If A is a two dimensional array with the first column containing the price of products and the second column containing the quantity sold, {A[0]*A[1]} produces a column array containing the value of the stock sold.

A is the 2 dimensional array {{4.5,6.7,5.5,2,6},{1,3,6,3,2}}

A[0] is the 1 dimensional array {4.5,6.7,5.5,2,6}

A[1] is the 1 dimensional array {1,3,6,3,2}

A[0] * A[1] is the 1 dimensional array {4.5,20.1,33,6,12}

{A[0]*A[1]} is the 2 dimensional column array {{4.5,20.1,33,6,12}}


Matmul (Matrix Multiplication)
MatMul - Matrix Multiplication

This function multiplies two arrays, treating them as matrices. It takes the form matmul{A,B} where A and B are the two arrays to be multiplied. Matrix multiplication is not commutative, the order in which the arrays are multiplied is A * B.

Any elements missing from the arrays are taken as zeroes.

Example:

matmul {{{1,0},{-4,3}} , {{13,-9},{2,-3}} } = {{49,-27},{14,-9}}

If, for instance, you had an array of N points stored as B[N][3], and a transformation array T[3][3], then to transform all of the points use the expression B := Matmul{T,B}.  The height of the returned array is the width of T, while the width of the returned array is the width of B.

This function is standard Matrix Multiplication.

 The normal multiplication * does not perform matrix multiplication, rather it multiplies corresponding elements of the arrays.


/ Division Operator

The exact operation of the division operator depends on the objects being divided, the list below gives the sensible actions that this operation performs.

For the conventions used in this document see Conventions.

Unlike Multiplication, division is not commutative (a/b is no the same as b/a), hence the order of the operands is important.

Numeric / Numeric	Dividing Numeric types returns the quotient (the result) as the higher type of object. For example 2@ / 3.2 returns 0.625 as a double precision number. (Integer  / double returns a double because it has more precision and hence is a higher type of object).

Error / Any Object	Dividing an Error by anything, return the Error unchanged.

Complex / Complex	Division of two complex numbers returns the complex quotient, e.g. (2+3j) / (3+3j) returns 0.8333333+0.16666666j. Note that the preceding expression needs to be bracketed since division has a higher precedence than addition. Without the brackets 2+3j / 3+3j would be evaluated as 2+(3j/3)+3j.

Array / Numeric	Dividing an Array by a Numeric, divides all elements of that array separately. e.g.

Array / Array	Divides corresponding elements of the arrays e.g. .


% Percentage Operator

This operator is exactly equivalent to dividing by the number 100. It is mainly used to enter percentages into a worksheet.

Example

50% is 50/100 is 0.5

For an full list of actions that this operator can perform, see the Division Operator.

When used to input a number, % will divide by 100. When used in the display format to display a number, % will multiply by 100.


? Modulus Operator

The modulus operator returns the remainder of a division. For example, 4 ? 3 is 1, four divided by three is 1 remainder 1.

The modulus operator is similar to division in that it operates differently on different objects. The following list gives the useful combinations.

For the conventions used in this document see Conventions.

Numeric ? Numeric	Returns the modulus (the remainder) of the equivalent division. e.g. 4?3 = 1

Complex ? Complex	The result of this calculation is produced by dividing the complex number by the divisor, the real and imaginary parts are then processed to remove any integer part, leaving only the fraction, finally the result is multipled by the divisor. Notice that this is not the Modulus part of {Mod, Arg} form for a complex number. e.g. (32+4i)?3i = (2+1i). Modulus has a higher precedence than addition, so the brackets are needed, otherwise this expression would appear as 32+(4i ? 3i).

Array ? Numeric	Returns the array, with each element separately evaluated using the normal modulus rules. e.g.

Array ? Array	The modulus is applied to corresponding elements of the array e.g.

See also the Division Operator.


^ Raise to the Power Operator

The ^ operator raises the first value to the power of the second, e.g. 2^2 returns 4,  3.2 ^ 6 returns 1073.472.

The returned type is always double (a double precision floating point number).

Complex numbers can be raised to a power, i.e. (2+3j)^2 returns -5+12j and can be return as the result of a calculation, e.g. (-3)^0.5 returns 0 + 1.7320508j


#& Bitwise AND Operator

Converts any numeric object to an integer value, and then performs a boolean logic bitwise AND on the numbers, returning the integer result e.g. 5@ #& 4@ returns 4@, 20.7 #& 7.0001 returns 4.

Applying a bitwise AND to an array performs the AND on each element in turn if a single value is used, while an AND involving two arrays performs the AND on corresponding elements.


#| Bitwise OR Operator

This function converts any numeric object to an integer value, and then performs a boolean logic bitwise OR on the numbers, returning the integer result e.g. 5@ #| 4@ returns 5@, 20.7 #| 7.0001 returns 23.

Applying a bitwise OR to an array performs the OR on each element in turn if a single value is used, while an OR involving two arrays performs the OR on corresponding elements, e.g.


#| Bitwise XOR Operator
#~ Bitwise XOR Operator

This function converts any numeric object to an integer value, and then performs a boolean logic bitwise XOR on the numbers, returning the integer result e.g. 5@ #~ 4@ returns 1@, 20.7 #~ 7.0001 returns 19.

Applying a bitwise XOR to an array performs the XOR on each element in turn if a single value is used, while an XOR involving two arrays performs the XOR on corresponding elements, e.g.


#>Bitwise Right Shift Operator

This function converts any numeric object to an integer value, and then performs a logical shift right by the specified number of bits, returning the integer result e.g. 23@ #> 2@ returns 5@, 200.7 #~ 3.0001 returns 25.

Note that zeros are shifted into the upper bits.

Applying a right shift to an array performs the shift on each element in turn if a single value is used, while a right shift  involving two arrays performs the shift on corresponding elements, e.g.


#< Bitwise Left Shift Operator

This converts any numeric object to an integer value, and then performs a logical shift left by the specified number of bits (using a shift count greater than 32 acts the same as 32), returning the integer result e.g. 23@ #< 2@ returns 92@, 200.7 #~ 3.0001 returns 1600.

Applying a left shift to an array performs the shift on each element in turn if a single value is used, while a left shift  involving two arrays performs the shift on corresponding elements, e.g.


= Equality and != Inequalities

= Equality Operator

This operators tests for equality between two compared objects, returning a Boolean TRUE if the objects are the same, and a Boolean FALSE if they aren't.

!= Inequality Operator

The inequality operator is exactly the reverse of the equality operator, returning TRUE if the objects are not identical.

Rules

For a list of conventions used, see Conventions

Numeric = Numeric	Numeric objects (of whatever form) are always compared by value. If the values are the same to within 1e-15th of their magnitudes, then the numerics are equal. This small value is to allow for slight rounding errors within floating point numbers.

Complex = Complex	An equality test on two complex number objects will only return TRUE if both the real and imaginary parts have the same values in each object - all other values will return a FALSE result. Again, a slight error of 1e-15th of their value is allowed.

Array = Array	An equality test on two lists or arrays will only return TRUE if all corresponding element are equal, e.g.

Null = Numeric	A value of zero (0) is consider equal to a NULL object

Null = String	An Null is considered equal to a string if the string has not characters and hence no length.

String = String	Two strings are considered equal if they match character by character, ignoring the case or attributes (accents, cedillas etc.) of any letters. Any punctuation character is equivalent to any other punctuation character found at the same offset in each string, i.e. "clean-sheet" = "clean?sheet"  but "clean-sheet" = "cleanasheet".

Error = Error	Error objects can be compared. The same rules apply as for strings.

Date = Date	Date objects are compared like for like. Two dates are consider equal if they represent the same day, e.g. \12/06/93 = \12th June 1993 = \Saturday, 12 June 93

Time = Time	Time objects are also compared like for like, e.g., 11:12pm = 23:12:00 = 11:12:00pm


< and > Greater Than and Less Than

The < and > operators compare two objects to determine their relative values - is one less than, or greater than, the other.  A boolean TRUE or FALSE object is returned.

Rules

For a list of conventions used, see Conventions

The list of rules mostly represent the Greater Than comparison, to obtain the Less Than comparison, simple swap the left and right sides of the > sign.

Numeric > Numeric	Numeric objects are compared by value, returning TRUE if the left is greater than the second.

String > String	Strings are compared according to their relative position in the alphabet, e.g. "Nigel" > "Fred" will return TRUE, while "B" < "A" returns FALSE.  Accented characters within the string have the accents ignored during comparison and upper and lower case are treated equally.

Date > Date	Date objects are compared chronologically e.g. \12/06/93 > \11th June 1993

Time > Time	Time objects are compared on a 24-hour clock basis, with midnight being 00:00:00.

Complex numbers cannot be compared for magnitude, it is mathematically non-sensical so do so.


<= and >= Less Than or Equal, Greater Than or Equal
<= and >= Less Than or Equals and Greater than Or Equals

These comparisons are composites of the Greater Than and Equals, and the Less Than and Equal comparison. Their behaviour is therefore very predictable.

Rules

For a list of conventions used, see Conventions

Numeric >= Numeric	Numeric objects are compared by value, returning TRUE if the left is greater than or equal to the second.

String >= String	Strings are compared according to their relative position in the alphabet, e.g. "Nigel" >= "Fred" will return TRUE, while "B" <= "A" returns FALSE.  Accented characters within the string have the accents ignored during comparison and upper and lower case are treated equally, hence "John" >= "JOHN"

Date >= Date	Date objects are compared chronologically e.g. \12/06/93 >= \11th June 1993

Time >= Time	Time objects are compared on a 24-hour clock basis, with midnight being 00:00:00.

Complex numbers cannot be compared for magnitude, but they can be compared for equality hence this operator returns TRUE if they are equal, and FALSE if they are not.


! Logical NOT Operator

The logical Not, reverses the sense of any comparisons. To do this it must be to the left of the comparison, or object.

 When placed to the right of a calculation, this operator behaves as a Factorial function.

Examples

!TRUE = FALSE	Not TRUE equals FALSE

!(1=2) = TRUE	(1=2) is FALSE, the NOT operator reverse this to make it TRUE

See Also

! Factorial Operator


! Factorial Operator

The Factorial Operator, returns the factorial of the number to the left of it. It must be to the right of the calculation.

When the exclamation mark is to the left of a calculation this operator behaves as a Logical NOT, rather than Factorial.

The Factorial function is defined as  n! = n (n-1) (n-2)....1 and as such it only operates on integers. When used on a floating point number, the number is rounded. The returned result is always of type Double, since this operation can produce very large numbers.

30! = 2.6525e32

When the Factorial is an intermediate, as is often the case for statistical functions, the SparseFact function may be more appropriate as this does not overflow so easily.

See Also

! Logical NOT Operator


& Grouping AND

The & operator groups several related comparisons into one composite.

If both sides are TRUE (or non-zero for numeric values), then a Boolean TRUE is returned. In other words they group comparisons together.

Example:

(a=2 & b=2) is TRUE only if a=2 AND b=2


| Grouping OR

The | operator groups several related comparisons into one composite.

If either side is TRUE (or non-zero for numeric values), then a Boolean TRUE is returned. In other words this operator groups comparisons together.

Example:

(a=2 | b=2) is TRUE only if either a=2 OR b=2


>=<,>==<,>===<,>====< Vague Equalities

The above operators all access the Compare function, to test that two objects are equal within a specified % of error.  The number of '=' symbols give the % error to use, having the ranges +/- 5%, +/- 10%, +/- 25% and +/- 50% respectively.  They all return a Boolean TRUE or FALSE result.

These are another example of the Vague Logic operations within CleanSheet, you will find examples of Vague Logic facilities throughout CleanSheet.

For example, the test "Nigel Johnstone" >==< "Nigel Johnson" returns TRUE, but the test "Nigel Johnstone" >=< "Nigel Johnson" returns FALSE.

Note that the >< signs point inwards to indicate that the result is within a specified range of vagueness. Also notice that the narrower the symbol the narrower the tolerance to differences.

It helps to think of these operators by associating names with them, for example  A >=< B means A is very close to B. A>====<B mean A is fairly close to B and so on.


<=>,<==>,<===>,<====> Vague Inequalities

The above operators all access the Compare function, to test that two objects are equal within a specified % of error.  The number of '=' symbols give the % error to use, having the ranges +/- 5%, +/- 10%, +/- 25% and +/- 50% respectively.  They all return a Boolean TRUE or FALSE result.

These operators are an example of the Vague Logic operations within CleanSheet.

Note that the <> signs point outwards to indicate that the result of the compare is outside the specified range of vagueness.

It helps to think of these by names, for example A<====>B means that A is very different from B, ( A is not close to B). It may also help to think of these in terms of negative equalities. For example A<=>B is not A is close to B.

Example, the test "Nigel Johnstone" <==> "Nigel Johns" returns TRUE, but the test "Nigel Johnstone" <==> "Nigel Johnson" returns FALSE, i.e., they are NOT unequal hence they are equal. The second example returns FALSE because the names are too similar to be considered unequal.


>>, >>>, >>>>, >>>>> Vague Greater Than

The above comparison operators all perform relational tests between two objects, returning a Boolean TRUE or FALSE value, they compare objects using the Compare function within Clean Sheet's Vague Logic comparison engine.

a >> b Indicates that a is greater than b and outside a the 5% error band over which the objects could be considered equal.

10 >> 9 returns TRUE (difference is > +/- 5%), while 10 >> 9.6 returns FALSE.

It helps to think of these operators by names, for example >>> is very much greater than. Similarly >> means slightly greater than and so on.


<<,<<<,<<<<,<<<<< Vague Less Than

The above comparison operators all perform relational tests between two objects, returning a Boolean TRUE or FALSE value, they compare objects using the Compare function within Clean Sheet's Vague Logic comparison engine.

a << b Indicates that a is Less Than b and outside a the 5% error band over which the objects could be considered equal.

9 <<<< 10 returns FALSE, because 9 is too close to 10 to be considered as Less Than.

It helps to think of these operators by names, for example <<<< is very much less than. Similarly << is slightly less than and so on.


Comparison Operators

Comparison Operators available within CleanSheet

= Equality and != Inequalities

< and > Greater Than and Less Than

<= and >= Less Than or Equals and Greater than Or Equals

! Logical NOT Operator

& Grouping AND

| Grouping OR

Vague Logic Comparators available within CleanSheet

>=<,>==<,>===<,>====< Vague Equalities

<=>,<==>,<===>,<====> Vague Inequalities

>>, >>>, >>>>, >>>>> Vague Greater Than

<<,<<<,<<<<,<<<<< Vague Less Than

See Also

Compare


:= Assign to Variable

Assigns an objects 'value' to a variable name. Assignments should only be made inside the computer object and used inside a program. Do not use them inside the Input Grid or any other object that simple evaluates a function and converts it to an immediate answer.

The variable is just a place holder, it has no type of its own, it takes the type of the variable it contains.

Example Assignments

MyString := 1@;	Assigns the Integer 1 to the variable MyString

MyString := "Hi There"	Assigns the String "Hi There" to the variable MyString

MyString := {1,2} 	Assigns an Array to MyString. Note that this example implicitly defines an array object.

Promoting during Assignments

You can assign to part of a variable using the assignment operator, this effectively promotes it to an array if it is not already one.

MyVar := {"hello",34.5} 	Creates an array of two elements in which MyVar[0], is equal to "hello", and MyVar[1], equal to 34.5.

MyVar := "hello" 	Assign the string object "hello" to  'MyVar'. This replaces the previous contents of MyVar.

MyVar[1] := 34.5	Implicitly converts MyVar to an array, keeping the original value as element [0]. My treating an object as an array, you implicitly promote it to an array.

MyVar[1][3] := 10	Adds a further dimension to MyVar, converting element [1] into an array in its own right, i.e. MyVar[1] becomes the list {34.5,null,null,10}

The whole of MyVar now contains {"hello",{34.5,null,null,10}}

See Also Arrays.

Replacing Sections of Variables using :=

An assignment may also to used to replace a value or section of a string, in a similar manner to the way Overdimensioning extracts parts of objects.

Example:

MyDate := \12th Jan 1966	Assigns the date \12th Jan 1966 to the variable MyDate

MyDate{0} := 10	Then assigns 10 to replace part 0 - the Day of Month part. After this is done, MyDate now contains 10th Jan 1966 as a date.

Example:

MyString := "hello how"	Assigns the string "hello how" to the variable MyString.

MyString{6} := "this is an example"

Assigns the string "this is an example" to character 6 onwards in the original string.

MyString now contains "hello this is an example"


+=,-=,*= ...Complex Assign to Variable
+=, -=, *=....Complex Assign to Variable

Complex assignments are simple contractions of an operator and an assignment. a/=2 expands to a := a / 2 conversely a := a + 2 can be written as a += 2.

If MyArrayA := {{2,3},{4,5}} and MyArrayB := {2,4}, then

MyArrayA := MyArray A * MyArrayB

 can be written as

MyArrayA *= MyArrayB

The full list is:

#~=	Bitwise XOR

^=	Raise to the Power

#&=	Bitwise AND

#|=	Bitwise OR

#>=	Right Shift

#<=	Left Shift

+=	Add

-=	Subtract

*=	Multiply

/=	Divide

?=	Modulus

See Also

:= Assign to Variable


Data Object Types

In contrast to existing spreadsheets, CleanSheet has a wider range of data types for information beyond the traditional numeric & string formats.

This range of object types allows CleanSheet to handle a wider range of calculations in a more logical and consistent manner.  For example, although some spreadsheets supports the idea of complex numbers, these are stored as strings. Therefore, to add two complex numbers requires the use of a special function.  In a similar manner, operations on arrays are limited to two-dimensional arrays, since it is difficult to represent a higher-dimensional array on a flat grid. This multiplicity of types allows CleanSheet to understand, that adding two complex numbers should return a complex result.

Within CleanSheet, a particular piece of information can be one of several 'types'; these are known by the particular type values shown below:

Type	Description

0	Null Object.i.e., Nothing

1	Integers, ranging from -2147483678 to +2147483647

2	Reals;  A floating point number, having 6 significant decimal places and a range of -1E-38 to 1E38.

3	Reals; A double length floating point number, having 15 internally significant decimal places and a range of  -1E-308 to 1E308.

4	A String of characters; the maximum length is 32767 characters.

5	Boolean Logic TRUE/FALSE.

6	An Error object - used to signal error conditions.

7	A Date object.

8	A Time object.

9	A Complex number.

10	An Equation.

11	An Array object.

These numbers can be obtained by using the function Type


Null
The Null Object

Null is the absence of other data object. When a pipe is empty, or a function returns nothing, it actually returns a NULL object.

When writing programs, any variable that has not been initialised contains a NULL.

Think of NULL as the absence of other objects.


Integers
Integers Objects

Integers are whole numeric values (no decimal point) within the range -2147483678 to +2147483647.

They may be entered directly into an input grid cell, be assigned to a variable, appear as constant values in a calculation, or shown as an output item.

To enter an integer into CleanSheet, type the number followed immediately by an @ symbol.

For example 3@ is the integer 3. Similarly 3.4@ is truncated to the integer 3 and stored as an integer.

If you omit the @, then the number you type is taken as a double real number. This is true even if the number has no decimal places. 3 is a double 3@ is an integer.

Integer objects may also be used to hold a sequence of (up to) four characters, i.e.,

'A' is an integer (value 65) representing 'A'

'AB' is an integer (value (65 * 256) + 66) representing 'AB'


Single Real Floating Point Numbers
Single Reals (C Type Floats)

Single Reals are floating-point values, to 6 significant decimal places, within a range of -1E-38 to +1E+38.  They cannot be directly entered into CleanSheet, but can be produced by Make{}  and some other functions.

Single Reals are a much more compact form of floating point number and hence their main use is for storage where the space consumed is more important than the precision.

See Double Reals for details on CleanSheets normal numeric objects.


Double Precision Numbers
Double Reals

Double Reals (called Doubles for short) are the normal type of number objects within CleanSheet.  Values are held to 15 significant decimal places, within the range -1E-308 to +1E308.  Like integers,  they may be entered directly into an input grid cell, assigned to a variable, appear as constants, or shown on an output item.

Examples

3.45

15.29e+3	The number 15290.

3	The double 3.0000000, to specify an integer you must use the @ symbol.

When you enter a number into CleanSheet, if there is not qualifying symbol after it (such as @ for integers, colon for Time objects etc.), then it is assumed to be a Double Real Floating point number.


String Types
Strings

Strings hold a sequence of characters, up to a maximum length of 32767 characters.  They are distinguished from other types (when entering into an input grid cell) by starting with a leading '"' character ( a double quote character).

e.g. "This is a sample string".

Note that characters surrounded by single quotes are converted to an Integers.

Contrast:

'a'	The Number 96 representing character 'a'

with

"a"	The String, consisting of the letter "a".


Boolean Objects

Boolean items are logical TRUE or FALSE objects; these are entered into an input grid as the names 'FALSE' and 'TRUE'. They are also returned by comparison operators, for example 3>2 returns a Boolean TRUE.


Error Objects

Error objects are returned by CleanSheet when an expression cannot be evaluated. For example the expression

\12th Jan 1992 + "This is a test string" 	;will produce a result

Q007 Error: Attempt to add mismatched objects type 7 and 4.

You can use the function 'Type' which returns the type of an object to detect errors within your CleanSheet programs.

Some errors cause programs to stop, these Run Time errors represent faults within a program, while the less serious represent faults within a calculation.
An error will cause a program running in the Computer Object if it begins with and 'R'.

You can create your own errors within programs using the Make{} function, but remember, if they begin with an 'R' then they will terminate your program.

See Also

Error List


Date Objects

Date objects are, quite literally, dates. A date object is declared by starting a constant or input cell entry with the '\' character (note that this is a backslash character rather than a forward slash - top left to bottom right).  CleanSheet will then do its best to interpret the characters that follow as a valid date. For example

\12th Jan 1966
\12 Jan 66
\12/1/66	In the UK English edition this is treated as 12th Jan 1966
\1/14/66	Because 14 can only be a day of the month, it is taken as 14th Jan 66

When parts of the date are missing, the current system date is used to complete it. For example \3rd September would be interpreted as 3rd September 1993, if typed during the year 1993.

Some things are unacceptable within the date formats.
A dash (-) is not allowed since subtraction is a valid operation on date objects.
A dot is not allowed as a separator because it is used internally by CleanSheet.
Backslash is not allowed, since this is used to specify a date object.

Examples of bad date objects:

\12\1\66 	Incorrect due to the use of backslash.
\12-1-66	Incorrect due to the use of dash.
12/1/66	Missing backslash at start of date.


Time Objects

A time object is used to store a time value, in HH:MM:SS form.  It is entered by separating the three items with the ':' (colon) character.  If the seconds field is omitted, a default value of 00 seconds is used.  The entry may be followed with an 'am' or 'pm' indicator if a twelve hour format is required, otherwise a 24-hour clock is assumed.

For example

12:03

12:05:04

11:05am

11:06pm

Note that the am / pm immediately follows the numbers without any separating spaces.


Complex Numbers

Complex numbers are simply entered as the real+imaginary values, as one composite item. To enter a complex number in CleanSheet, the imaginary part must immediately be followed by an i or j. For example 3+2j is a complex number, but 3+2  j is incorrect, due to the space between the 2 and j.

They can also be reversed 2j+3 is the same as 3+2j is the same as 3+2i . The i is usually used in mathematics, whereas the j is usually used in engineering notations.

Complex numbers can also be returned by expressions that evaluate to the complex domain. For example sqrt(-2) return the complex number 0+2i.


Equation Objects

Equation objects are used by CleanSheet to define program code and equations, and are stored in a special tokenised form.  Their main use is for functions such as LineFit, which fits a line to a set of points and return an equation object defining the result.

Equation objects cannot be directly entered into CleanSheet, instead they are returned as results by some of its functions (mainly the Make{} function and FitLine{} )

Note: an equation object is not the same as an equation entered into a worksheet. Naturally you can type equations directly into a worksheet, you cannot however create an equation object by directly typing one in.


Array Objects
Arrays

An array is a group of other CleanSheet data objects, such as numbers, strings, dates etc.. These objects can be mixed freely, in other words you are not restricted to having only numbers in an array, or only dates.

All arrays in CleanSheet are zero based, i.e. the first entry is entry zero.

The array object can comprise of an array of single types of a base object, or any combination of base objects stored within particular elements, e.g.,

MyInts[0] = 1@	; here MyInts is an array of two integers

MyInts[1] = 2@

while

Composite[0] = "hello"	; is a three element array comprising a string,

Composite[1] = 123 + 24j	; a complex number,

Composite[2] = {1234,8279}	; and an array of 2 numbers.

Notice that the array 'Composite' is an array of 3 elements, the third of which is itself an array. Each element is independent of the others.

Arrays can have up to 10 dimensions (i.e. A[1][2][3][4][5][6][7][8][9][10]).

Array Constants

Arrays are initialised by enclosing the list of elements within {} characters; for example,

{1,2,3,4,5}	; Is a one-dimensional array with 5 elements

{{1,2}.{3,4}}	; Is the two-by-two array

Note that the first dimension of the array runs across, and the second dimension runs down.

You should be careful to distinguish between the use of {} when initialising arrays, and when accessing sub-sections of an object via overdimensioning.

When used to represent 2 dimensional arrays, it is often easier to think of them as grids.

See Also

Indexing into Arrays

Promotion to Array Objects


Indexing into Arrays

Indexing into an array can be specified in several forms. For, say, the 2 by 2 variable X, containing the array {{1,2}.{3.4}}, access to individual items can be done as follows:

X[0]	; returns the list {1,2}, while

X[1][1]	; returns the value 4, and

X[1][0][1]	; returns the value NULL (since nothing has been assigned here)

Note this last example also has the implicit action of promoting the array element x[1][0] into an array itself. After you have requested element X[1][0][1],  X[1][0] becomes an array of 2 elements, the first of which is  the number 3. The action of refering to a variable or part of a variable as though it were an array promotes it into being an array.

Further Example:

Y:={{"A Sample","Array"},{"Of Strings"}};

Therefore:

Y[0] is the array {"A Sample","Array"}

and hence

Y[0][1] is the string "Array".

The index into the array can be given in several styles.  You can:

Use separate parameters for each index, e.g. X[1][2]

Use an array list within {}'s, e.g. X[{1,2}] is equivalent to X[1][2].

Use complex numbers to index into arrays e.g. X[3+2i] is equivalent to X[3][2]

Use time objects to index into arrays e.g. X[12:03:50] is equivalent to X[12][3][50]

The second form of indexing is extremely useful for CleanSheet function such as Search{} and Nearest{}. When Search finds a matching object in an array it needs to return where it was found. In order to do this, it returns an array.

The following fragment of code illustrates this (taken from a Computer Object)

/* Initialise x to contain the original data */

x:={{"John Smith","John Smyth","Paul Smith"},{"Joanne Smith","Pauline Smith"}};

/* Search for the Nearest Match for "Paul Smyth" */

a:=Nearest{ x ,"Paul Smyth"};

/* Nearest returns the array {0,2} indicating the x[0][2] contains the nearest match*/

b:=x[a];

/* Now b containts x[a] which is x[{0,2}] which is x[0][2] which is "Paul Smith" */

These methods of access can be used in any combinations of styles you like, to gain access to a given element of an array, e.g.

array[1][2][3]	; returns the same as

array[1][{2,3}]	;

array[{1,2,3}]	;

array[{1,2}][3]	; etc. etc.


Promotion of Simple types

Simply by implying that a variable is an array, promotes it to an array.

Notice that a single variable of a simple type is implicitly promoted to an array. Simply indexing into that variable within an expression will cause the variable to be promoted.  For example, given the simple integer variable 'J', initialised in a program via

J := 3@

then the following all promote J to an array:

J[2] := 5@	; promotes to the list {3,NULL,5}

J[0]	; promotes to the list {3}.

J[1] := "Smith"	; promotes to the list {3,"Smith"}

while

J[2][1] := 6	; promotes to the array {3,NULL,{NULL,6}}

Note the second example carefully. 'J[0] '. This doesn't assign anything to the variable J, but simply by referring to J as though it is an array, implicitly makes it into one.


Overdimensioning

For some data objects, part of the data can be extracted separately using a technique known as overdimensionsing. This is done by placing a value in {}'s immediately after the object, to select just a subset of the object in question; this is best explained by examples:

Given the constant string "Mr. Smith grows day by day", then using overdimensioning as follows

"Mr. Smith grows day by day"{3}	; returns the 'S' of Smith, while

"Mr. Smith grows day by day"{15}	; returns the 'd' of  the first 'day'

Overdimensioned access can only be used on certain types of  objects - the data that has multiple parts to it.

Note that all the items extracted via overdimensioning are returned as a double floating point number  - this should be particularly noted when using overdimensioning on strings - the first example doesn't actually return letter 'S' it returns 83.0 the code for 'S'.

The following examples are all illustrated with fragments of CleanSheet program code, to use these you must be entering the fragment into a Computer Object, they cannot be entered into the Input Object.

Complex - Overdimensioned complex numbers return either the real or imaginary part depending on the value used i.e.,

Complex := 123 + 4j

Complex{0}	; returns the real part (123)

Complex{1}	; returns the imaginary part (4,  NOT 4j)

Dates	- Overdimensioned dates return the day, month and year from items 0, 1 and 2 respectively, where day is 1 through 31, month 1 through 12 (Jan is 1), and year is the complete century and year (e.g. 1993).

bd := \26th Jan 62	; initialise bd with a date

bd{0}	; returns 26	- the day of month

bd{1}	; returns 1	- month of year

bd{2}	; returns 1962 - Year

Times	- Overdimensioned times return hours, minutes and seconds as items 0, 1 and 2.

Current :=09:11:18	;Assign a Time object to 'Current'

Current{0}	; returns 9	Hours

Current{1}	; returns 11	Minutes

Current{2} 	; returns 18	Seconds

Strings - Overdimensioned strings return a (single) character from the string, e.g.

MyString := "Four score years and ten"

MyString{6}	; returns the character 'c'

MyString{0}	; returns 'F'

Strings are based on the ANSI character set, thus the above would return 99 as the value. If you use a value as the overdimension argument that is greater than the current string length, then the string is extended (by adding spaces) to the required length  e.g.

MyString := "Hello"	; if current length is 5 characters

MyString{10}	; then access beyond string length... sets

MyString equal to "Hello<5 spaces>"

This is another example of implicit promotion of variables. By implying that the string is longer that it really is, you extend the string.

Sections of a string may be replaced, by assigning a value to an overdimensioned access to a string, e.g. given

MyString := "This is a T"

then

MyString{10} := 83	; sets MyString to "This is a S", and

MyString{2} := "at"	; sets MyString to "That is a S", while

MyInt := 87@	; Value for 'W'

MyString{0} := MyInt	; sets MyString to "What is a S", and

MyString{11} := "ponge"	; sets MyString to "What is a Sponge"

Equations	- Equations that have been returned by a function (e.g. LineFit) can also have overdimensioning applied to them;  however, this will return the byte token from the equation, in CleanSheets internal format.

See Also

Promotion

Assign to Variable

Indexing into Arrays


Error Return Codes (Predefined)
Predefined Error Return Codes

The following list covers errors returned by expressions, CleanSheet functions and programs written by the user. Errors beginning with 'Q' are expression errors and are non-fatal. Errors beginning 'R' are Run Time errors in Cesk CleanSheet programs, and will cause the program to abort. Other code letters are warnings from CleanSheet to the User and are non-fatal.

Where <num> is shown in the error, a number will be displayed which represents the data object type, a list of these numbers is available in Data Types.

Errors Q001 to Q010

Errors Q011 to Q025

Errors C, W, S, F

Errors R


Errors Q001 to Q010
Q001 Error: attempt to add mismatch objects types <Num> and <Num>

An attempt has been made to add two data items whose types are incompatible.

Q002 Error: Bit operation on mismatched objects types <Num> and <Num>

Bit operations such as AND, OR, XOR can only be performed on numeric objects, an attempt to perform a bit operation on another data type results in this error.

Q003 Error: Cannot take inverse

It was not possible to take the inverse of an object, because the object has no inverse, or the type of object is incorrect. For example Matrices with a determinant of 0 have no inverse.

Q004 Error: Wrong object type

The wrong type of object was encountered in a function requiring specific object types.

Q005 Error: Cannot convert object <Num> to <Num>

The Make function and similar functions perform conversions from one object type to another, this error will be returned if a request for an illegal conversion is made.

Q006 Error: Numerical overflow

A numerical overflow of the Floating Point routines.

Q007 Error: action performed on mismatched objects types <Num> and <Num>

This is returned by operators and functions when the objects are ill matched. The commonest use of this is in multiplication, for example "String1"*"String2" is illegal as you cannot multiple two strings.

Q008 Error: String too long

String objects can be no larger than 32767 characters long.

Q009 Error: Division by zero

Attempt to divide by zero.

Q010 Error: Cannot evaluate complex power

Attempts to raise an object to a complex power e.g. 2^(3+2i) are not allowed.


Errors Q11 Onwards
Q011 Error: attempt to sub mismatched objects types <Num> and <Num>

Attempt to subtract objects that cannot be subtracted.

Q012 Error: Incorrect function parameters

This is the commonest error within CleanSheet. When data is passed to a function, if the function expects particular types of parameter and receives different, it returns this error as a function return.

Q013 Error: Two many parameters

More parameters than allowed have been passed to a function. The exact number of parameters required depends on the function.

Q014 Error: Two few parameters

Too few parameters were passed to a function that was expecting more.

Q015 Error: Number too large to display

When the user specifies a number format for displaying numbers that limits the range of numbers available (for example n% cannot display very large numbers because it cannot have an exponent), and an attempt is made to display a very large number, this error is displayed.

Q016 Error: Maths Domain error in <Name>

The calculation went outside the allowable Domain. This is a floating point error, <Name> gives the name of the function that failed.

Q017 Error: Maths Singularity  Error in <Name>

The floating point package reported a singularity in the function <Name>.

Q018 Error: Maths Overflow Error in <Name>

The floating point package reported an overflow condition in function <Name>.

Q019 Error: Maths Partial Loss of Significance in <Name>

The floating point package reported a partial loss of significance in function <Name>, for significance, read accuracy.

Q020 Error: Maths Total Loss of Significance in <Name>

The floating point package reported a loss of accuracy.

Q021 Error: Maths Underflow in <Name>

The floating point package has lost its accuracy because the numbers have gotten too small.

Q022 Error: Maths Invalid Operation

An invalidate operation was performed by the floating point package. The exact meaning is not known.

Q023 Error: Maths Overflow

A floating point package overflow occurred in the normal multiplication, division and addition operators.

Q024 Error: Maths Underflow

A floating point underflow (number too small to store) occurred in the normal multiplication, division, addition operators.

Q025 Error: Maths Error

A general error, other than the predefined types occurred in the floating point package during the normal multiplication, addition and division operators.


Errors F, S, C W
F001 Error: Filing Clerk - no filename specified

No filename has been set inside a Filing Clerk object, so it cannot write to disk.

F002 Error: Filing Clerk - error with filename

The filename specified in the Filing Clerk is invalid.

S001 Error: Savings/Loans Object - Too many numbers in Present_Value, Future_Value, or Number_of_Periods.

Only one number is allowed for Present_Value, Future_Value or number of periods in a SAL calculation.

C001 Error: Reporter-Announcer nested too deep.

Reporter-Announcer object pairs can only be nested 3 deep.

C002 Error: Object too big to handle.

When a Reporter is assembling an object, if the object is larger than 64k, then this error will be returned.

W001 Warning: It is not necessary to use an equals sign to specify an equation.

When entering an equation into an Input Table, it is common to type =2+3 or similar construct if you have just switched over from another Spreadsheet. This is not strictly allowed, but is tolerated by CleanSheet, which will report a Warning.


Errors R
R001 Error: Incorrect assignment

An attempt has been made to assign data to something that is not a variable.

R002 Error: unbalanced brackets [<Num>] {<Num>} (<Num>)

When a program is tokenised (prepared for execution), or when the user types in an equation and the brackets mismatch, this error is displayed on the Status line. The <NUM> in this case represents a count of each type of brackets, +ve numbers mean too many opening brackets, -ve numbers mean too many closing brackets.

R003 Error: Syntax

An unexpected command or item was hit when executing a CeSk program.

R004 Error: Faulty Action Clause in IF

The Action clause of an IF command within a CleanSheet program is incorrect, or missing.

IF (condition-clause) action-clause;

R005 Error: Faulty ELSE Clause in IF

The Else clause within a CeSk program is missing or faulty. This is only relevant when ELSE is specified.

IF (condition-clause) action-clause ELSE else-clause;

R006 Error: Malformed WHILE

Badly formed WHILE loop in a program. A common error is to omit the condition.

WHILE (condition) { Action };

R007 Error: WHILE not terminated correctly

The WHILE loop was not terminated correctly by a semi-colon after the closing bracket or statement.

R008 Error: Malformed DO

A DO loop within a CleanSheet program is incorrectly set, the correct form for a DO loop is:

DO { action} while (condition);

R009 Error: DO not terminated correctly

The final semi-colon after a DO-loop within a CeSk program is missing.

R010 Error: Malformed Condition in FOR

The condition part of a FOR loop is incorrect, the correct form is:

FOR (Init-action ; condition; post-action;) {main -action};

R011 Error: Malformed PostOp in FOR

The Post action in a FOR loop is badly formed. Unlike the programming language C, a semi-colon is required after this action.

FOR (Init-action; condition; post-action;) {main-action};

R012 Error: Malformed Action in FOR

The main action clause within a FOR loop is madly formed.

FOR (init-action; condition; post-action;) {main-action};

R013 Error: FOR incorrectly terminated

A FOR loop is not terminated by a semi-colon;

R014 Error: Missing ( in FOR

A FOR loops main group is contained within a set of braces (). This error occurs if these braces are omitted.

R015 Error: Illegal command in FOR

It is not allowed to place FOR, DO, WHILE loops etc., within the initialisation, condition, or Post-Op phase of a FOR loop.

R016 Error: Expression does not evaluate

When an expression for a loop condition was evaluated, it evaluated to nothing (not even a NULL object) and hence this expression does not evaluate.

R017 Error: CASE/DEFAULT does not evaluate

The specifier in a CASE construct does not evaluate to any value and so could not be compared.

R018 Error: No such function

When a call is made to a function, and no function can be found with a name that matches, this error is returned.

R019 Error: Attempt to break/Continue out of a function

Break and Continues are used within program loops. If the program is not in a loop when these commands are used, then this error will occur.

R020 Error: Cannot find object

Reserved for internal use.

R021 Error: Program Terminated by User.

When running a Computer Program, if the user clicks on STOP in the Variables Tracking windows, then this error is returned by the Computer Object as a result.


Function Arguments

Functions within CleanSheet always take just one parameter as an argument. This may at first seem like a serious limitation, however the single parameter can be any type of CleanSheet data object - including an Array.

Functions that require more than one piece of data accept an array as input. Using the array system means that any number of parameters can be passed or even variable numbers of parameters.

When a function requires just one parameter, the single data object is passed to it. Where functions require more than one parameter, an array of parameters is passed.

For example, the function EXP (exponential) requires just 1 parameter, hence

EXP(2.3), which returns 9.974

Note the rounded brackets, indicating that EXP is a function taking just one parameter; these are no obligatory, but make it easier for you to follow the declaration e.g. EXP(2.3) = EXP 2.3.

The function ATAN2, however, requires two parameters.  These must be passed as a single array, e.g. given MyArray := {23,12}, then

ATAN2({23,12}) = ATAN2{23,12} = ATAN2 MyArray

ATAN2 23,12 or ATAN2(23,12)

The last two return an error because neither of them are grouped into an array using the curly brackets.


True

The True function returns a Boolean TRUE object.

This function takes no parameters.


False

The False function returns a Boolean FALSE object.

This function takes no parameters.


Null Function

The Null function returns a Null object.

This function takes no parameters.


Now

Now returns a time object for the current system time.

This function takes no parameters.


Today

Today returns a date object for the current system date.

This function takes no parameters.


Exp

This function calculates the value of e^x where e is 2.71828...

The Exp function takes either a single numeric argument N and returns the value of e^N, or a complex number object, which returns a complex result,.

This function takes a single parameter as input, for information on calling function see Function Arguments.


Ln
Ln (Naperian Log)

The Ln function takes a single numeric argument, returning the Naperian log (log to the base e, where e is 2.71828...).

This function takes a single parameter as input, for information on calling function see Function Arguments.


log10

The log10 function returns the log to the base 10 of a single numeric argument.

This function takes a single parameter as input, for information on calling function see Function Arguments.


Int

The int function returns the integer portion of any single passed numeric object, e.g. int (2.3) returns 2, as does int(2.7).

This function takes a single parameter as input, for information on calling function see Function Arguments.


Sign

Sign returns the sign of the passed numeric argument, as the value +1, 0 or -1 for a positive, zero, or negative value, respectively.

This function takes a single parameter as input, for information on calling function see Function Arguments.


Sqrt

Returns the square root of the passed numeric or complex number argument.  If a negative numeric value is used, a complex number will be returned i.e. sqrt(-1) returns the complex number 0+1i.

This function takes a single parameter as input, for information on calling function see Function Arguments.


sinh, cosh, tanh
Sinh, Cosh & Tanh

These functions return hyperbolic sin, cosine, or tangent of the passed numeric value respectively.

These functions take a single parameter as input, for information on calling function see Function Arguments.


asinh, acosh, atanh
Asinh, Acosh & Atanh

These functions return the inverse hyperbolic sin, cosine, or tangent of the passed numeric value.

These functions take a single parameter as input, for information on calling function see Function Arguments.


sin, cos, tan
Sin, Cos & Tan

These functions return the sin, cosine or tangent of the passed numeric value. The angle is in radian, to convert from degrees to radians use DegToRad.

These functions take a single parameter as input, for information on calling function see Function Arguments.


asin, acos, atan
Asin, Acos & Atan

These functions return the inverse sin, inverse cosine and inverse tangent of the passed numeric value.

The returned angle is in Radians, to convert to degrees, see RadtoDeg.

These functions take a single parameter as input, for information on calling function see Function Arguments.


Sec, Cosec, Cot
Sec , Cosec & Cot

The Sec, CoSec, & Cot functions return the secant, cosecant, or cotangent of the passed numeric value. These functions require the angle to be specified in Radians, to convert degrees to radians use DegToRad.

These functions take a single parameter as input, for information on calling function see Function Arguments.


Asec, Acosec, Acot
Asec, Acosec & Acot

The ASec, ACoSec & ACot functions return the inverse secant, inverse cosecant, and inverse cotangent of the passed numeric value.

The returned angle is in Radians, to convert this to degrees see RadToDeg.

These functions take a single parameter as input, for information on calling function see Function Arguments.


Compare

The general basis function for all vague operations is the COMPARE function, which takes two objects (A & B) as arguments, compares them, and returns a value indicating how close the objects are.  This value is approximately scaled (where possible) to be a percentage in the range +/- 100.

A value of 0 (zero) means that the objects are the same.  A positive value means that  A > B, while a negative value means A < B.

If two objects of differing types are compared, e.g. a number and a string, then the relative rankings of the object types are used, and the value returned is always one of +/- 100.  For example, comparing a number (N) with a string (S) via COMPARE{N,S} will return +100, since strings rank 'higher' than numbers (a string can contain representations of numbers, but numbers cannot contain strings).

Numbers are compared and the difference between the values is scaled against the first of the two values; this may result is results outside the +/- 100 range, i.e.

COMPARE{1000,2000} returns -100, since A < B by 100%, but

COMPARE{100,2000} returns -1900, since (A-B) = -1900, which is then * (100/100), while

COMPARE{10,2000} returns -19900, since (A-B) = -1990 which is then * (100/10), and

COMPARE{2000,10} returns 99.5, since (A-B) = 1990 which is then * (100/2000)

Strings can be compared by using the COMPARE function. Case and accents on characters are ignored.  The value is calculated by comparing the letters within the strings, and to a lesser extent the position of the letters e.g.

COMPARE{"Nigel Johnstone","Nigel Johnston"}

returns 9.615, indicating that the strings are a pretty close match.  The returned value is positive, since "Nigel Johnstone" ranks greater than "Nigel Johnson" alphabetically.

Error objects can be compared with other error objects - an array of error objects could be scanned to find a corresponding error message in a string array, for instance.

Equation objects can be compared with another equation object.

Date objects can be compared with other date objects.  The result is scaled so that a one year difference (365 days) corresponds to the value +/- 100 exactly.  As per numbers, this may result in values greater than +/- 100, i.e.

COMPARE{\26/01/62,\26th Jan 1962} returns 0 (zero), while

COMPARE{\26/01/62,\26th Jan 1961} returns 100, and

COMPARE{\26/01/62,\26th Jan 1965} returns -300.274

The last result has decimal places since a leap year has occurred during the intervening time so the two dates are not exactly 365 days apart.

Time objects can be compared with other time objects, returning a value scaled by the first argument expressed as seconds since midnight, e.g.

compare{00:00:01,00:00:02} returns -100, since the difference is 1, and the scale 100/1, while

compare{23:59:58,23:59:59} returns -0.001, since the scale is now 100/86398.

Arrays are compared element by element, and the average of all the comparisons returned as the result, e.g.

compare{{2,3},{2,4}} returns -16.66

since compare{2,2} returns 0, and compare{3,4} returns -33.3, which is then averaged.

Complex numbers are compared using the sum of the differences of their real and imaginary parts, scaled to the magnitude of the first complex number; this can return results greater than +/- 100.


Mag

The mag function returns the magnitude of an object.

For a numeric object, this returns the absolute value e.g. mag(-2) returns 2.

For a string object, mag returns the length of the string, i.e. mag("Hi there") will return the value  8.

For a boolean object, TRUE will return a value of 1, while FALSE will return a value of 0.

When used on a date object, mag returns the number of days from 1st Jan 1900 (which is considered day 0).  Note that for dates prior to this a negative value will be returned, e.g. mag(\31st Dec 1899) returns the value -1.

When used on a time object, the number of seconds since midnight is returned.

For a complex number, mag returns the modulus part of the complex number, e.g. for a complex number a+bi, mag returns sqrt(a*a+b*b).

When the argument is a list or array, the argument is treated as a matrix.  A one dimension matrix (a list) is treated as a vector, and its length returned, e.g.

mag{10,20} equals sqrt(10*10+20*20) returns 22.36, while

mag{10,20,30} equals sqrt(10*10+20*20+30*30) returns 37.42

When applied to a 2  dimensional array, mag returns the determinant of the array.  This will work for any N x N array up to 16 * 16.

This function takes one parameter, for information on function calling conventions see Function Arguments.


Log

Log{a,b} returns the log of argument a to the base b, i.e. log{10,2} returns 3.322.

This function takes two parameter and hence the parameters must be grouped into an array, for information on function calling conventions see Function Arguments.


Round

This function rounds a number to the supplied number of decimal places.  Both parameters must be of  numeric type, e.g.

round{1.2359,2} returns 1.24, while

round{1234.234,-2} returns 1200

This function takes two parameter and hence the parameters must be grouped into an array, for information on function calling conventions see Function Arguments.


Atan2

Atan2 take either two numeric parameters, e.g. atan2{a,b}. returning the inverse tangent of b/a, along with the quadrant that the resulting angle lies in, according to the signs of the a and b values, OR a single complex number, which uses the real value as the first parameter, and the imaginary value as the second, i.e. atan2(a+bi), which returns the Arg value of the Modulus/Arg form for the complex number.  Note that when using a complex number, since only 1 (one) argument is being supplied, rounded brackets are used, rather than curly brackets.

For further information on passing parameters to a function see Function Arguments.


Pi

The Pi function returns the value of Pi (approximated to 3.14159265358979)

This function takes no argument.


Degtorad

Takes a single numeric argument, expressing a degree value, and returns the value in radians, e.g.

degtorad(100) returns 1.74532925.

This function takes one parameter, for information on function calling conventions see Function Arguments.


Radtodeg

Converts a single numeric value - an angle in radians, and returns the degree equivalent, e.g. radtodeg(1.745532925) returns 99.999...

This function takes one parameter, for information on function calling conventions see Function Arguments.


PtoR
Ptor (Polar to Rectangular)

ptor takes a polar coordinate in the form {r,theta}, and returns the rectangular coordinates {x,y} for the same point, in a two element array.  The polar expression may be given as a two element numeric array, or a complex number. The angle theta, is specified in radians.

e.g. ptor{10,1.5} returns {0.70737201,9.97494986}

This function takes one parameter, for information on function calling conventions see Function Arguments.


RtoP
Rtop (Rectangular to Polar)

rtop takes a pair of rectangular coordinates {x,y}, giving a point on a graph, and returns the polar values {r,theta} for the same point, as a two element array.  If a complex number is used as the rectangular coordinates, the Modulus/Arg form of the complex number is returned as a two element array.

The angle theta is in radians.

e.g. 	rtop{10,20} returns {22.360,1.107}

rtop{10+20i} returns {22.360,1.107}

rtop(10+20i) returns {22.360,1.107}

This function takes one parameter, for information on function calling conventions see Function Arguments.


PtoC
Ptoc (Polar to Complex)

ptoc takes an array of the form {r, theta}, giving a point on a graph, and returns the rectangular coordinates as complex number object (whereas ptor always returns a two element array). The angle theta is

e.g.	ptoc{10,1.5} returns 0.70737201+9.974949i

This function takes one parameter, for information on function calling conventions see Function Arguments.


Rand
Rand (Random Number)

Rand returns a decimal random number in the range 0 (zero) to 1 (one).

This function requires no arguments.


Geoseries

Geometric series generator.

geoseries takes a three element array, {n,a,r} and returns an array composed of the values a, ar, arr, arrr...arn-1. The second argument does not have to be a numeric value, this function can produce series from any objects that can be multiplied.

geoseries{3,4,5} will return the array {4,20,100}
geoseries{3,"Hi",2} returns {"Hi","HiHi","HiHiHiHi"}


Ariseries

Arithmetic series generator.

ariseries, like geoseries, take a three element array, {n,a,r}, and returns an array comprising the arithmetic series {a,a+r,a+r+r...a+r(n-1)}.  Again, the second argument does not have to be a numeric value.

ariseries{3,4,5} returns the array {4,9,14}
ariseries{5,\Jan 1st 92,30} will return 5 dates, at 30 day intervals, i.e., {\1st Jan 92, \31st Jan 92, \1st March 92, \31st March 92,\30th April 92}


Size

The size function returns a value representing the size of an object, in accordance with the table below

Null	Size is always 0

Integer	Size is always 1

Float	Size is always 1

Double	Size is always 1

String	Size is the length of the string in characters

Boolean	Size is always 1

Error	Size is the length of the error string in characters

Time	Size is always 1

Date	Size is always 1

Equation	Size is the length of the equation token list in bytes

Arrays	Size is the number of elements

Notice that the Size of an array returns the number of elements, this is the number of elements in the first dimensions, for example size {{1,2,3},{4,5,6}} returns 2 because the array is a 2 elements array, {1,2,3} and {4,5,6}.

See Also Data Types.


Type

The Type function returns a numeric value representing the type of the object, as shown below

Type	Description

0	Null Object (i.e. nothing) . Note that this is not the same as zero, or a zero-length string.

1	Integers, ranging from -2147483678 to +2147483647

2	Reals;  A floating point value, having 6 significant decimal places and a range of -1E-38 to 1E38.

3	Reals; A double length floating point value, having 15 significant decimal places and a range of  -1E-308 to 1E308.

4	A String of characters; maximum length is 32767 characters.

5	Boolean True or False.

6	An error object.

7	A date object.

8	A time object.

9	A Complex number.

10	An equation.

11	An array object.

See Also Data Types


Invert

Invert returns the inverted value of a numeric, complex, boolean or array object. The exact operation depends on the object being inverted:

Numeric values:	invert(-2) returns 2 (i.e. a numeric just has the sign changed)

Complex Numbers:	invert(a+bi) returns a-bi, the complex conjugate

Boolean Object:	invert(FALSE) returns TRUE

If the object is an array, the array is treated as a matrix and the inverse of the matrix is returned.  Should the matrix not be already square (i.e. NxN), then the array is extended using zero valued elements until it is square.


Weekday

Weekday will test a date object and return a numeric value corresponding to the day of the week, where Sunday is taken as 0, e.g.

weekday(\27th June 92) returns 6 (i.e. Saturday)

0 = Sunday

1 = Monday

2= Tuesday

3 = Wednesday

4 = Thursday

5 = Friday

6 = Saturday


Transpose

Transpose takes an array argument and transposes the first 2 dimensions. For example,

transpose{{1,2,3},{4,5,6},{7,8,9}} returns {{1,4,7},{2,5,8},{3,6,9}}, i.e.

Note that a similar transpose using array notation is transpose{{"hello","array"},{"follow","on"}} which returns {{"hello","follow"},{"array","on"}}


Extract

Extract is used to pick out a subset of an array or string object.  Its general form is

extract{object,lower_index,upper_index}

Extract on Strings

For a string object, it extracts a subsection of the string using the following rules:

The lower and upper index values are inclusive (the characters they specify are included in the result)

If the lower index is less than zero, it is taken as zero (i.e. start at the first character)

If the upper index is greater than the length of the string, only return the remaining characters upto the end of the string.

If the upper index is less than the lower index, return a null (empty) string.

Given the above, then for the string MyString := "this is an example",

extract{MyString,3,8} returns "s is a"
extract{MyString,3,3} returns "s"
extract{MyString,-2,3} returns "this"
extract{MyString,11,200} returns "example", and
extract{MyString,200,11} returns ""

Extract on Arrays

For an array object, extraction is not so easy to grasp, as the object may be multi-dimensional.

On a simple one dimensional array, the extraction is similar in concept to a string, i.e. given the array MyArrayA := {"abc","def","ghi","jkl"}, then extract{MyArrayA,1,2} returns the array {"def","ghi"}.

On a two dimensional array, MyArrayB := {{"abc",123},{"def",456},{"ghi",789}} then extract{MyArrayB,1,2} will return the array {{"def",456},{"ghi",789}}

However, if you now provide an array of index values as the lower and upper bounds, then, for example, given the array

MyArrayC := {{"abc",123,\7th April 92}, {"def",456,\7th June 92}, {"ghi",789,\11th June 92}}

which would be shown in written form as (outer values 0,1,2 are written to guide you on the positions, they are not part of the array)

then extract{MyArrayC,{1,1},{2,2}} returns the array  {{456,\7th June 92}, {789,\11th June 92}}, which would be shown as:

 (again, the outer values are for guidance only)

while extract{MyArrayC,{0,1},{0,2}} would return {{123,\7th April 92}}.

Notice the double curly brackets -  the last examples return value could equally be expressed as a one dimensional array, but because the extraction is returning part of a column, additional brackets are used to group related column elements; In a similar manner, extraction of a row subset via the expression extract{MyArray3,{1,1},{1,2}} would return the result {{456},{789}}, showing that two values from the same row but differing columns were extracted.

Extract, when used on an array object, is N-dimensional.  For instance, a cube could be extracted from a four (or higher) dimensional array by using the lower and upper bounds of {1,1,1} to {2,2,2}.

Other object types may be used as the lower and upper bounds, i.e. the complex numbers 4+3i and 6+9i could be used (extract{MyArrayC,4+3i,6+9i}) which is the same as extract{MyArrayC,{4,3},{6,9}}, while time objects would be taken as a 3 part reference, e.g. extract{MyArrayC,12:30:25,12:40:56} is the same as extract{MyArrayC,{12,30,25},{12,40,56}}


Remove

Remove is a complementary function to extract;  Like extract, it takes three parameters of object, lower_bound and upper_bound, but it the returns all items that are outside the specified region.

Remove on Strings

Removes the specified range of characters from the character string and closes up the gap. The first character is character 0. The range includes the upper and lower bounds, so it you remove 3 to 4, this removes character 3 and character 4.

For example:

remove{"This is a string",4,8} would return "This string"

Remove on Arrays

When applied to arrays, this function removes the specified range of array elements and closes the gaps.

Remove{{"abc","def","ghi","jkl"},1,2} would return {"abc","jkl"}

On a two dimensional array, MyArrayB := {{"abc",123},{"def",456},{"ghi",789}} then remove{MyArrayB,1,2} will return the array {{"abc",123}}

However, if you now provide an array of index values as the lower and upper bounds, then remove can remove multi-dimensional sections of arrays.

Examples:

MyArrayC := {{"abc",123,\7th April 92}, {"def",456,\7th June 92}, {"ghi",789,\11th June 92}}

which would be shown in written form as (the outer values are for guidance only)

then remove{MyArrayC,{1,1},{2,2}} returns the array  {{"abc",123,\7th April 92},{"def"},{"ghi"}} ,  which would be shown as (the outer values are for guidance only)

while remove{MyArrayC,{0,1},{0,2}} would return {{"abc"},{"def",456,\7th June 92},{"ghi",789,\11th June 92}}.

Other object types may be used as the lower and upper bounds, i.e. the complex numbers 4+3i and 6+9i could be used; remove{MyArrayC,4+3i,6+9i}) is the same as remove{MyArrayC,{4,3},{6,9}}. Time objects would be taken as a 3 part reference, e.g. remove{MyArrayC,12:30:25,12:40:56} is the same as remove{MyArrayC,{12,30,25},{12,40,56}}


InsDim1
InsDim1 (Insert into the first dimension)

InsDim1 can be used to place characters into a string object, or insert null objects at given elements within an array's first dimension.

In both cases, the generic form of the function is InsDim1{object,start_position,items}.

Applied to Strings

When used on a string object, it insert the item_string into the source object at the specified position.  If the insertion point is beyond the current length of the string then the string is automatically padded with spaces to reach the required insertion point. Thus, for example, if MyString := "A String", then

InsDim1{MyString,1," Simple"} returns "A Simple String", while

InsDim1{MyString,12,"extended"} returns "A String    extended"

This can also be used to insert string objects into equation objects in a similar manner.

When Applied to Arrays

In the case of an array, InsDim1 will place null objects into the first dimension of the array, e.g., given the array MyArray := {{"abc","def","ghi"},{123,456,789}} then InsDim1{abc,1,2} results in the array

Note carefully that the elements that are blank are not set to NULL - they are unassigned, and have no value at all. If you try to examine these entries then they appear as Nulls, but because they are not stored, they do not take up space in the computers memory.


InsDim2
InsDim2 (Insert into Second Dimension)

InsDim2 has a similar effect to InsDim1, placing the inserted values into the second dimension of the array, rather than the first. Unlike InsDim1, this function only works on arrays, since string objects have no second dimension.

It takes the form InsDim2{object,start_position,num_item} - Inserting num_item nulls into the object at the specified start_position.

Given the example MyArray := {{"abc","def","ghi"},{123,456,789}} then InsDim2{MyArray,1,2} returns the array


Proper

When used on a string object, the proper function returns the string with each initial letter of a word capitalised, all other letters being converted to lower case, e.g.

proper("tHOse vAlueS") returns "Those Values"

When passed a date or time object, proper converts the date or time to the correct representation, e.g.

proper(\30th Feb 92) returns \1st Mar 92, and

proper(12:61:66) returns 13:02:06


Lower

The lower  function converts all alphabetic characters in the passed string to lower case.

Lower("This is A TEST") returns "this is a test"


Upper

Upper converts all alphabetic characters in the passed string to upper case.

Upper("This is A TEST") return "THIS IS A TEST"


Clean

Clean removes all characters with codes (according to the ANSI tables) less than 32 or greater than 127 from the passed string, returning the cleaned string.


Trim

Trim converts all whitespace (comprising spaces, tabs, cr/lf etc.) within a string into a single space, (in other words it trims needless white space) e.g.

trim("This	is   a    test") returns "This is a test"


Dot

The Dot function calculates the scalar (dot) product of two vectors.  A vector can be either a complex number, which is treated as a 2 element vector, or a 2 or 3 element array. For example,

dot{2+3i,3+4j} is equal to dot{{2,3},{3,4}}, both returning 18, while

dot{{1,2,3},{4,5,6}} returns 32

When taking the dot product of a 2-element and 3-element vector, the 2- element vector is considered to have a third component of value 0 (zero).

dot{{1,2,3},{4,5}} is equivalent to dot{{1,2,3},{4,5,0}}


Angle

Angle calculates and returns the angle (in radians) between two vectors e.g. if A := {2,1,-3} and B := {1,2,1}, then Angle{A,B} will return 1.4615 (radians).

The vectors can be specified using complex number:

Angle{2+3i,4+2i} returns 0.51914611 radians.


Cross

Cross calculates and returns the cross product of two vectors, i.e. if A := {2,1,-3} and B := {1,2,1}, then cross{A,B} returns 9.11


Search

The search function is used to find objects within strings or arrays.

Its generic form is Search{Object,Item,Optional_start_position}.  If no start position is given, then Search will start at the lowest possible bound for the object i.e. first character of a string, or element (0,0...) of an array. Should no match can be found, the value -1 is returned.

Search applied to Strings

For string and equation objects, the item to search for can be a string or value.  For example

search{"This is a sample","is"} returns the value 2

search{"This is a sample","IS",3} returns 5

search{"This is a sample,65} returns 8, since ANSI code 65 is taken as 'A'

Note that the case is ignored while searching, thus "is" is the same as "IS" for the comparison checks.

Search applied to Arrays

When used on arrays, Search can return either a numeric value or array.  For a simple list, a numeric value will be returned, e.g. Search{{"abc","def",123,"ghi"},"ghi"} will return the value 3. When searching through an array, it is necessary for search to specify several indices since the object found may be in the second or third dimensions of the array. To do this search returns an array specifying the position, for example {1,2} would be column 1, row 2 of the array.

A slightly more complex example follows. Given the array MyArray, initialised to be

then, if the search was on date of birth, to find the name of the person whose birthdate is the 16th June 54, the call would be

MyArray[search{MyArray,\16th June 54} [0]][0]

which would return "Paul Taylor".  Breaking the call down shows (i) The search returns {1,1}, giving (ii) MyArray[{1,1}[0]][0], which reduces to (iii) MyArray[1][0], giving (iv) the return "Paul Taylor".

In the same manner, when used on a 3 (or N) dimensional array, Search will return a 3 (or N)  element array is the item is found in the last dimension.

If MyArrayB := {{{123,456},{234,567},{456}},{{123,345},{123,452}}}  (shown below)

then search{MyArrayB,456} will return {0,0,1}, and search{MyArrayB,345} returns {1,0,1}.

Start positions for searching arrays can be specified in several forms, e.g. search{MyArrayB,456,1} would start the search at {1,0,0}, while search{MyArrayB,456,{1,2}} and search{MyArrayB,456,1+2i} would both start the search at {1,2,0}.

Search can also be used to search for complete arrays within arrays, e.g. if MyArrayC is set as

{{123,456},{789,124},{342,2835}} then search{MyArrayC,{342,2835}} will return the value 2, i.e. MyArray[2] is itself the array {342,2835}.


FullSearch

FullSearch, like Search, will scan through a supplied object, looking for a match on the supplied search item.  However, instead of returning just the first match, as Search does, FullSearch will return an array of all matching items within the scanned object.

Its generic form is FullSearch{Object,Item,Optional_Start_Position}.  It always returns any results as an array - the empty array {} if no match was found, or an array of positions where item was found.

Fullsearch on Strings

When used on strings, fullsearch returns an array containing the starting offset(s) where the search item was found within the string, e.g.

fullsearch("This is a sample string","is"} returns {2,5}

The string "is" was found at offsets 2 and 5 in the source string.

Fullsearch on Arrays

For arrays, Fullsearches searches for a matching object.

if MyArray:= {123,456,789,"abc","def",192,"abc"}, then

search{MyArray, "abc"} will return 3, while

fullsearch{MyArray,"abc"} will return the array {3,6}, since there are two matches, and

fullsearch{MyArray,"abc",4} will return {6}

On a 2 (or greater) dimensional array, fullsearch will return an array of array positions, e.g. given MyArrayB as

then fullsearch{MyArrayB,\16th Jun 54} will return {{1,1},{3,1}}, in other words the requested date occurs at {column 1, row1} and {column 3, row 1}.

To check that a valid match was found, you can use the Size function, which will return 0 for no matches.


VagueSearch

VagueSearch will search an array for a matching item whose Compare value is within the specified lower and upper bounds of vagueness - i.e. it searches for items that approximately match the supplied search value.

It generic form is expressed as VagueSearch{Array_Object, Search_Object, Lower_Limit, Upper_Limit, Start_Position}.

The object to be searched is always an array object, but like other search functions, the search object can be any of the other supported types, e.g. a string, a numeric, an array, etc.

The lower and upper limits impose the % vagueness to be used during a Compare; the lower limit may be different from the upper limit e.g. 5 and 10 will search for a lower match of the search item of - 5% to an upper match of + 10%.  Remember that Vague comparisons return values approximately scaled to +/- 100, where possible, so a lower limit of -5 and and upper limit of +5 will return a result (if found) that is within +/- 5%  - zero is equality.

The optional start position gives the initial element to start the search from, within the target array. Any unspecified indices are taken as an initial 0 (zero) value, i.e. a start position of 3 begins at {3,0,0,0...}, while a start position of {3,2,4} begins at {3,2,4,0,0,0...}.

As with other search type functions, no found match will result in the value -1, while the first match will be returned as the elements position within the array, e.g. VagueSearch{{1,10,100},95,-10,10} would return 2, while VagueSearch{{{1,10,100},{200,300,400}},399,-5,20} would return {1,2}.


FullVagueSearch

The FullVagueSearch function operates in the same manner as VagueSearch; however, it returns an array of all matching values, rather than just the first matching value.

It is called as FullVagueSearch{Array_Object,Search_Item,Lower_Limit,Upper_Limit,Optional_Start}.

FullVagueSearch searches Array_object, for an item that approximately matches Search_Item. Approximately is defined as between Lower_Limit and Upper_Limit when the two objects are Compared. The search is started from Optional_Start if it is specified, or from the start of the array if it is not.

As per the FullSearch function, no matches are returned as the null array {}.


Nearest

The Nearest function uses the comparison functions to examine an array object, looking for the nearest match to the supplied search value;  Its generic form is Nearest{Array_object,Search_Item, Optional_number_of_items}

When called without the optional number of items, Nearest returns a single value giving the position of the nearest value, e.g.

Nearest{{"John Smith","Jurgen Voorgang","N Johnstone","S Jones"},"Nigel Johnstone"}

returns 2, i.e. the second element is the nearest value.

For a 2 (or more) dimensional array, then an 2 element array is returned, giving the position, e.g.

Nearest{{{123,2343},{4314,212},{321,33}},32} returns the array {2,1}

meaning that column 2, row 1 contains the nearest match (which is 33).

If no match at all can be made on any item within the target array, then Nearest returns the value -1; Note however that Nearest returns the closest matching value of any compatible object e.g. Nearest{{22.7,23@,23.4},23.1} will return 1, as 23@ is the closest value, even though it is an integer. This also means that Nearest{{"1","2","3",10000},1} returns the position 3, because - even through the number 10000 isn't near to the number 1, it is the only number in the array and hence it is the nearest matching object.

When the search object is an array, then like Compare, the closeness of the search object to an element within the target array is taken as the average of the closeness of all the elements of the search object.

Searching for The N Nearest

If the optional number of items field (N) is used, then Nearest returns the N closest items as an array of positions, ranked into order of nearness. For example:

Nearest{{"J Smith","Jurgen Voorgang","N Johnstone","T Vard","S Johnson"},"Nigel Johnstone",2}

(Search the array for "Nigel Johnstone" and return the 2 nearest matches)

would return {2,4}, meaning that elements two and four are the two nearest objects (in ranked order, 2 is nearer than 4).


Farthest/Furthest

The Farthest/Furthest function is the converse function to Nearest; it returns the position of the object that is the worst match for the search object.

Either spelling of the function name is acceptable.

Its generic form is Farthest{Array_object,Search_Item, Optional_number_of_items}

When called without the optional number of items, Farthest returns a single value giving the position of the most dissimilar object, e.g.

Farthest{{"John Smith","Jurgen Voorgang","N Johnstone","S Jones"},"Nigel Johnstone"}

(search the array for the string that is least like the string "Nigel Johnstone")

returns 3, i.e. the element 3 is the farthest value away from the search item.

For a 2 (or more) dimensional array, then an 2 (or more) element array is returned, giving the position, e.g.

Farthest{{{123,2343},{4314,212},{321,33}},32} returns the array {1,0} meaning that column 1, row 0 (which contains 4314) is the furthest away from 32.

If no match at all can be made on any item within the target array, then the value -1 is returned;
Note however that Farthest returns the most distant matching value of any object, if an incompatible object is included, then this will have the Vagueness value of 100, which may represent the furthest object.

e.g. Furthest{{1,2,3,"test"},4} returns 3, meaning that "test" is the worst match for the number 4.

When the search object is an array, then like Compare, the distance of the search object to an element within the target array is taken as the average of the distance of all the elements of the search object.

If the optional number of items field is used, then Farthest returns the N most distant items as an array of positions, ranked into order of distance away. For example:

Farthest{{"J Smith","Jurgen Voorgang","N Johnstone","T Vard","S Johnson"},"Nigel Johnstone",2}

(Search the array and find the two Least similar strings to the string "Nigel Johnstone")

would return {3,1}, meaning that elements 3 and 1 are the two most distant objects (in ranked order, 3 is furthest away, 1 is the next furthest).


Vague Logic

CleanSheet implements a form a fuzzy logic to help it perform consistent operations with data. CleanSheets implementation is called the Vague Logic Engine and it drives a lot of the sheet and database facilities.

CleanSheet has 12 different types of defined data. With so many different types it was necessary to implement a strict strategy for comparing any two pieces of data, whatever their type. How for example, do you sort a list which contains complex numbers, when you can't compare complex numbers for magnitude? The Vague Logic engine addresses this and many other problems in a consistent manner.

At the lower level, the Vague Engine drives the Compare function and the Vague Comparators.

>=<,>==<,>===<,>====< Vague Equalities

<=>,<==>,<===>,<====> Vague Inequalities

>>, >>>, >>>>, >>>>> Vague Greater Than

<<,<<<,<<<<,<<<<< Vague Less Than

Compare

At the next level, it drives Search functions within the expression evaluator.

VagueSearch

FullVagueSearch

Nearest

Furthest

At also drives Sort function.

NearSort1

FarSort1

NearSort2

FarSort2

At the Object Level, the engine can be found driving parts of a lot of the objects, including:

The Input Table's Search and Sort.

The Database Filter's Comparisons.

The Database Sort's, sorting order.

The Lookup Object's 'Find Nearest' option.

Even at the user interface level, the Vague Logic engine drives the Advisor.

With such a wide ranging feature, the best place to start is with the Compare function. This provides access to the Raw comparison algorythm.


UpSort1

UpSort1 sorts the columns of the passed array object into ascending order, by reference to a particular row.

The general form is UpSort1{Array_Object,optional_sort_element}

If you omit the sort element, element 0 is taken.

For example, given MyArray := {{123,1435}, {323,434},{4910,1928}}, then UpSort1{MyArray} will return the array unaltered (since the elements 123,323 and 4910 are already in order), while UpSort1{MyArray,1} will return the array {{323,434},{123,1435},{4910,1928}} - now row 1 in each column is in ascending order 434,1435 and 1928.

When comparing element objects within the array, CleanSheet uses the general comparison functions, so that strings will be sorted into ascending alphabetical order.

Arrays of complex numbers cannot be sorted, since it is not possible to compare complex numbers for magnitude.


DownSort1

DownSort1 sorts the columns of an array into descending order by reference to a specified row.

The general form is DownSort1{Array_Object,optional_sort_element}

If you omit the sort element, element 0 is taken.

For example, given MyArray := {{123,1435}, {323,434},{4910,1928}}, then DownSort1{MyArray} will return the array {{4910,1928},{323,434},{123,1435}}. The sort element was omitted and therefore the first element was taken 4910,323,123.

DownSort1{MyArray,1} returns {{4910,1928},{123,1435},{323,434}} , element 1 of each array is now sorted into descending order,  1928,1435 and 434.


UpSort2

UpSort2 sorts an array object by its second dimension (the rows) into ascending order with reference to the specified column. If no column is specified, then the first column is taken as reference.  For example, given MyArray := {{123,1435},{323,434},{4910,1928}}.

then UpSort2{MyArray} returns the array as is.

While if you specify that column 2 is the reference column, using:

UpSort2{MyArray,2} will return the arrays {{434,323},{1435,132},{1928,4910}}

Element 2 of the rows is now in ascending order.

Complex numbers cannot be sorted because they cannot be compared for magnitude.


DownSort2

This is the reverse of UpSort2; the values are sorted into descending order.

DownSort2 sorts an array object by its second dimension (the rows) into descending with reference to the specified column. If no column is specified, then the first column is taken as reference.  For example, given MyArray := {{123,1435},{323,434},{4910,1928}}.

then DownSort2{MyArray} returns the array with the rows swapped so that 1435 and 123 are in descending order.

While if you specify that column 2 is the reference column, using:

DownSort2{MyArray,2} will return the arrays as it is.

Element 2 of the rows are already in descending order (4910,1928).

Complex numbers cannot be sorted because they cannot be compared for magnitude.


NearSort1
NearSort1{Sort_Array,Comparsion_object,Array_Index}

Sorts the passed array on its first dimension, according to how near the element values are to the supplied comparison value.  If no index value is provided, 0 (zero) is assumed.

For example, given

MyArrayA := {124,231,523,231,928,294}, then NearSort1{MyArrayA,500} will return the array {523,294,231,231,124,928} i.e. closest to 500, followed by next closest, and so on.

while

MyArrayB := {{434,323},{1435,132},{1928,4910}} then NearSort1{MyArrayB,4000,1} returns the array {{1928,4910},{434,323},{1435,132}}, since 4910 (i.e. element 1 of the columns) is the closest value, and 132 the farthest.


FarSort1
FarSort1{Sort Array,Comparison object,Array Index}

FarSort1 is the complementary function to NearSort1; it takes exactly the same arguments, but the return array is ranked by farthest value first, then next farthest. and so on.

Example:

MyArrayA := {124,231,523,231,928,294}, then FarSort1{MyArrayA,500} will return

the array {928,124,231,294,523} i.e. furthest object is 928, followed by next furthest 124, and so on.

while MyArrayB := {{434,323},{1435,132},{1928,4910}} then FarSort1{MyArrayB,4000,1} returns the array {{1435,132},{434,323},{1928,4910}}, since 132 (element 1 of the first column) is the furthest from 4000, and 4910 the nearest..


NearSort2
NearSort2{Sort_Array,Comparison_Object,Array_Index}

NearSort2 operates in the same manner as NearSort1, but sorts on the second dimension of the passed array, returning a sorted array in the order - closest, next closest and so on.

For example if MyArray:={{"Smith","Jones","Johnson"},{1800,1220,600},{2000,800,1450}};

NearSort2{MyArray,"Johnstone",0} will sort the array with reference to column number 0 in terms of how near this entry is to the string "Johnstone".

In Array notation the result is {{"Johnson","Jones","Smith},{600,1220,1800},{1450,800,200}}.


FarSort2
FarSort2{Sort_Array,Comparison_Object,Array_Index}

FarSort2 operates in the same manner as FarSort1, but sorts on the second dimension of the passed array, returning sorted array in the order, furthest, next furthest.... nearest.

In other words it sort the rows in terms or the columns.

For example if MyArray:={{"Smith","Jones","Johnson"},{1800,1220,600},{2000,800,1450}};

FarSort2{MyArray,1300,1} will sort the array with reference to column number 1 in terms of how far away this entry is from the number 1300.

In this case 600 is the furthest away, 1800 the next furthest and 1220 the nearest.


Days360
Days360{Date_Object,Date_Object}

The Days360 function calculates the difference in days between the two supplied date objects, assuming each year to be always 360 days, and each month 30 days; this assumption is used within some financial calculations.

For example, Days360{\28th Jun 92,\12th Jan 66} returns 9526 (days) i.e. (92-66)*360 + (6-

1)*30 + (28-12).


Make
Make{Object, Optional_New_Object_Type}

Make is one of the most powerful functions within CleanSheet, allowing conversion of the supplied object into the new object type. Within this function is a whole wealth of powerful features.

Essentially this function converts one object type (See Data Types) to another, but since CleanSheet types include equations, complex numbers and so on, the conversion process provides a range of very useful conversions.

No Conversions

If the requested conversion type is the same as the original object, then no conversion is done; the original object is simply returned 'as is'.

e.g. Make{"A String",4} returns "A String" since type 4 is the string type.

Make on String Objects.

When converting a string object to another type, in general it is assumed that the string object contains an expression to be evaluated.  The string object is converted into an equation object, which is then evaluated.  The output of the expression is then converted to the requested object type, or to a Null object if conversion is not possible, e.g. Make{"\28th Feb 92 + 3"} will return the date object \2nd Mar 92.

Note that since no type conversion is given, the string is evaluated and returned exactly as if the equation \28th Feb 92 + 3 was typed in.
Omitting the type causes Make to return the evaluated type.

A slightly different example is:

Make{"2@ + 3@",3}  here the string is evaluated to give the integer 5@. Type 3 is a double precision type and so the finished integer is then converted to a double precision number.

 If you specify a particular type to convert to, then whatever the string evaluates to is then converted to that type.

Make with Numeric Objects

If a numeric value is supplied as the source object, and if no output object type is given, a default conversion to string type is assumed, i.e.. Make{32.34,4} is the same as Make{32.34} and returns the string of characters "32.34".

Type 4 is a string object.

If a numeric value is converted to a string, then normally the default format currently set is used to determine the format of the string; however, you can override this by explicitly giving the format to use as the second parameter to Make, i.e. make{1032.34,"N.Nx"} results in a string representation of the value as "1,032.34".  There is a large collection of predefined formats, e.g. Make{3.2,CurrencyForm} would return £3.20 for the UK version and $3.20 for the USA version; for a complete description of these see Standard Number Formats. For a list of the formatting characters you can use with make see Number Formatting Characters.

Make with Date Objects

If a date value is supplied, and no output format given, then it is assumed that a default conversion to string format should be done, e.g. Make{\12 Jan 92,4} is the same as Make{\12 Jan 92} and results in a string object "12th Jan 92".

As per numbers, you can also give a specific conversion format that the date should be styled to, i.e.

make{\1st Jan 86,"%S-%d-%n-%y} returns a string "WED-1-1-1986".  Again, there are several formats already defined as defaults see Standard Date Formats.

For the list of available date formatting characters, see Date Formatting Characters.

Other Conversions

The remaining conversions simply apply a sensible change to the source object. For an exact list, see Other Conversions, which specifies the changes in detail.


Other Conversions

The conversions allowed for each type are listed below.

0 - Make{Object,0}	Convert to Null Object.
No matter what the original object type, the conversion to type zero always results in a Null object type being returned.

1 - Make{Object,1}	Convert to Integer type.
 Any type of numeric value, will be converted to an integer, by truncation of any fractional part.
 Date objects are converted to the number of days since 1st Jan 1900.
 Time objects are converted to the number of seconds since midnight.
 Boolean objects are converted to 0 (False) and 1 (True) values.
 Complex number objects have the imaginary part discarded and the real part treated as a numeric value.
 String objects are assumed to contain expression (e.g. "2 + 2"), which are evaluated and any result of the calculation returned, such return being treated as a numeric value.
 Arrays and Error objects cannot be converted by this method (though individual array elements can).

2 - Make{Object,2}	Convert to Floating Point Type.
The same rules apply for type 2 conversions as appear in type 1 conversions; the only difference is that the result is a floating point value.

3 - Make{Object,3}	Convert to Double Type.
Type 3 conversions apply the same rules as type 1 and 2 conversions; the output is a double precision floating point value.

4 - Make{Object,4}	Convert to String type.
Any object converted to a type 4 value gets converted to its string representation.
Null objects are converted to null strings i.e. "".
Numbers (both simple and complex) are converted to string representations, according to the current default format styling set for that numeric type , e.g. -2.37 converted with a format style of S00.000 will result in the string "-02.370".
Dates are converted to strings, according to the current default date format.
Arrays are converted into array notation, i.e. "{{12,43},{\12th Jan 92}}"
Boolean objects are converted into the strings "FALSE" and "TRUE", respectively.
Equation objects are converted from their tokenised form into a string, e.g. "1 + cos(X)".

5 - make{Object,5}	Convert to Boolean Type.
Any numeric value may be converted to boolean by use of this call.  If the supplied numeric value (of whatever form) is zero, the FALSE is returned, otherwise a TRUE value is returned.

6 - Make{String,6}	Convert to Error Type.
Type 6 conversions are one of the two conversions that will only work on string objects (instead of a range of objects) - It will convert the string object into an error object.  Any CleanSheet programs can use this to flag errors to CleanSheet.

7 - Make{Object,7}	Convert to Date Type.
Type 7 conversions return a date object when passed a numeric value, by treating the value as the number of days since 1st Jan 1900.
For equation and string objects, the equation or string is evaluated as a calculation, and any numeric result converted as above.  If evaluation of the equation or string does not result in a simple numeric value, then a Null object is returned.

8 - Make{Object,8}	Convert to Time Type.
Type 8 conversions return a time object when passed a numeric value, by treating the value, modulus 86400, as the number of seconds from midnight (00:00:00).
For equation and string objects, the equation or string is evaluated as a calculation, and any numeric result converted as above.  If evaluation of the equation or string does not result in a simple numeric value, then a Null object is returned.

9 - Make{Object,9}	Convert to Complex Number Type.
A type 9 conversion takes a numeric value (of any form) and converts it to a complex number having an imaginary part of 0i.
A complex number object is simply returned unchanged.
Equation and string objects are evaluated for a numeric result, treated as above.

10 -Make{String,10}	Convert to Equation Type.
Type 10 conversions are the second that only take strings as the input object.  They return a tokenised equation form of the string e.g. Make{"sin(X) * cos(Y)",10} will return the internal equation object for the expression Sin(X) * Cos(Y). CleanSheet performs this tokenisation on its programs and any expression you type in.


Standard Number Formats

There are a number of formats predefined for conversion of objects to strings. These are for use with the make{} function.

GeneralForm -	Returns a string in the format "n.nx", the general form for displaying numeric values, for example, make{323123123212123,GeneralForm} returns the string "3.2312312321213e14".

CurrencyForm -	Returns a string in the format "£n.00". Note that this form will change to match whatever is relevant for the country that you are working in, e.g. "$n.00" for the US, etc.

CommaCurrencyForm -	Returns a string in the format "£N.00"; when the value requires it, commas are inserted separating each group e.g. Make{1234223,CommaCurrencyForm} will return the string "£12,342.23", rather than the "£12342.23" of CurrencyForm.

CommaIntCurrencyForm -	Returns a string in the format "£N", i.e. just the integer portion of any value. This is used when you are not interested in any fractional part of the amount.

ScientificForm -	Returns a string in the form "n.ne", a value always expressed with an exponent, e.g. Make{100.456,ScientificForm} returns "1.00456e2"

PercentageForm -	Returns a string in the form "n.n%", expressing the value as a percentage i.e. Make{0.456,PercentageForm} returns "45.6%"

PercentageIntForm -	Returns a string of the form "n%", expressing the value as an integer percentage, i.e. Make{0.456,PercentageIntForm} returns "46%".

LedgerForm -	Returns a string of the form "b£n.00", which gives positive values as per CurrencyForm, but will show negative values within bracket.  For example, Make{200.345,LedgerForm} returns the string "£200.35", while Make{-200.345,LedgerForm} returns the string "(£200.35)".

LedgerIntForm -	Returns a string in the same format as LedgerForm, using the integer value of the supplied number.

FractionForm -	FractionForm returns a string in the form "n.nx/*n", which, when used on a numeric, will attempt to express the value as a fraction, e.g. Make{0.333...,FractionForm} returns the string "1/3", while Make{0.0000324342,FractionForm} returns "3.23342e-5", since this cannot be expressed as a fraction.

SignedForm -	Returns the string in the form "sn.nx", always returning the numeric value with a '+' or '-' sign prefix, for positive and negative values respectively.

IntegerForm -	Returns a string in the form "N", i.e. the integral number closest to the supplied value. For example, Make{12.34,IntegerForm} returns "12".

SignedIntForm -	Returns a string of the form "sN", a signed version of IntegerForm, starting the string with a '+' or '-' sign as required.

LastNumForm -	Whenever a number is converted from its string form, the format used to represent the number is recorded, and may be recalled as LastNumForm; this will be one of the general, percentage, or currency formats.

For a list of the character formatting codes, see Number Formatting Characters.


Standard Time Formats

There are a number of standard time formats defined for use with the Make{} function.

Time24Form -	Returns a string of the form "n:*00:*00" for a time object, ensuring a 24-hour display format, e.g. Make{9:2:57,Time24Form} returns "09:02:57", while Make{1:13pm,Time24Form} will return "13:13:00".

Time12Form -	Returns a string of the form "an:*00:*00", showing the time object in 12 hour format with a trailing am/pm.

ShortTime24Form -	Returns a string of "n:*00" form, e.g. the same as Time24Form without any seconds being displayed.

ShortTime12Form -	Returns the short version of Time12Form, i.e. the time without seconds, using the format "an:*00".

LastTimeForm -	When a time object is extracted from a string, the format of the time object within the source string is analysed and stored as LastTimeForm; this may then be used when generating new string representations of time objects, e.g. Make{"1:13pm",8} will set LastTimeForm to the format string "an:*00".

The time formats are defined using the same character codes as the number formats. For a list of these characters, see Number Formatting Codes.


Standard Date Formats

There are a number of standard date formats defined for use with the Make{} function.

FormalDateForm -	Returns a string of the form "%w %e %m %y" from a date object, e.g. Make{\2nd July 92,FormalDateForm} returns "Thursday, 2nd July 1992".

FullDateForm -	Returns a date object in the format "%s %e %a %Y", giving the complete date with abbreviated names e.g. Make{\2nd Jul 92,FullDateForm} returns "Thurs, 2nd Jul 92".

ShortDateForm -	Produces a string of the form "%e %a %Y" from a supplied date object, e.g. Make{\2/6/92,ShortDateForm} returns "2nd Jul 92"

DateForm -	Returns a string in the form "%d/%n/%Y", e.g. the normal numeric form (dd/mm/yy, mm/dd/yy or yy/mm/dd) of a date object.  Note the order is dependent on the date format selected on your PC.

LastDateForm -	Whenever a date object is initialised from a string representation of the date, then the format of the string is analysed and stored; LastDateForm is this stored date form.  For example, Make{"\12th Jan 1992",7} returns a date object.  LastDateForm would be set to "%e %a %y", matching the entered date format from the string.

For a list of available character codes, see Date Formatting Codes.


Standard Complex Number Formats

The following is a list of standard conversion formats for converting Complex numbers using the Make{} function.

ComplexForm - 	Returns a string representation of a complex number value, in the format "n.nx*sn.nxi". For example, the complex number 12.45+3.2i returns the string "12.45+3.2i".

ComplexIntForm - 	Returns a complex number as a string, using the mask "n*sni", rounding any values to integers.

ComplexFixForm - 	Returns a complex number in a string using "n.00x*sn.00xi", producing the numeric values to 2 decimal places, e.g. "12.45+3.20i".

For a list of available formatting codes, see Number Formatting Codes.


MakeArray
MakeArray{Object,Count}

MakeArray may be used a quick method of making and initialising large arrays, all having the same initial value.  It takes an object to be copies, and value giving the number of times the object is to be replicated.

Because the array holding the objects is allocated in one pass and not extended piecemeal, MakeArray is quicker than a For loop,

e.g. MakeArray{"Hello",5} returns the array of string objects {"Hello","Hello","Hello","Hello","Hello"}.


Currency Symbols £ $ DM FF...
Currency Symbols (£ $ DM FF Lire Pts Yen Sf Bf DFI...)

When a currency symbol is attached to a numeric value, this indicates to the LastNumForm function that a currency representation was used.  When used on the first numeric entry to an input grid cell, it indicates that the default format for the rest of the grid cells should be set to this currency.

e.g. after £3.50 is executed, LastNumForm will be "£n.00"


Extrapolate
Extrapolate{Wanted_Item,Position_#1,Value_#1,Position_#2,Value_#2...}

Extrapolate is used to extend a range of data sets to obtain the required [unknown] item from a series.

Contrast this function with AriSeries and Geoseries function - these functions generate series by careful specification, while Extrapolate generates a series by example.

Wanted_Item is the position of the item required in the series.

Position_#1 and Value_#1 is the position in the series and value of the first known value.

Position_#2 and Value_#2 is the position in the series of the second known value.

You can provide as many or as few starting elements as you wish, subject to the limitation that some series need a minimum of three items to be identified.

Examples:

Extrapolate{5,1,100,2,200,3,300} Means that item 5 is wanted from a series in which item 1 is the number 100, item 2 is the number 200 and item 3 is the number 300.

The 5th element from the series (100,200,300...) is requested which is obviously 500, this is returned as the answer.

Extrapolate{{-10,10},1,100,2,200,3,300}

This example is based on the same series as the first; however, because the item requested is now an array rather than a simple value, {-10,10}, the result is an array of 21 values, {-1000,-900,...0...900,1000}.  Note that even if you specified a range covering only one value, e.g. {1,1}, because you supplied the item as an array, an array will be returned as the result, holding just the single item.

Since Extrapolate can work on most object types, including complex numbers, dates, times, and even whole arrays, it has significant functionality. There is also a very wide range of series it can spot.

Extrapolate{{1,10} ,2,2+4i, 4,12+8i, 5,17+10i}

This will be seen as an arithmetic series, and the result returned as {3+2i, 2+4i, 7+6i, 12+8i, 17+10i, 22+12i, 27+14i, 32+16i, 37+18i, 42+20i}.  The items in bold are the 3 values originally provided.

Extrapolate{5,1,\01/02/92,2,\28/02/92,3,\27/03/92}

This will return the date \19th May 92, since the dates are recognised as being a series at 27 day intervals.

Extrapolate{3, 1,\12th Jun 92, 2,\14th Jul 93, 4,\18th Sept 95}

This will return the date \16th Aug 94; Extrapolate spots that the days are increasing by 2, the months and years by 1, and extends the series for the day, month and year components of the date to get the return value.

Extrapolate{5, 1,\11th Jun 92, 2,\9th Jul 92, 3,\13th Aug 92}

This returns the date \8/10/92. Not so obvious? It's the second Thursday in every month; e.g., if a company wishes to pay each employee on the second Thursday of each month, a table of the relevant dates could be constructed as a variant on the above.

Extrapolate{5, 1,\27th Jan 92, 2,\24th Feb 92, 3,\30th Mar 92}

In a similar manner to the above, Extrapolate works out that this series is the last Monday in each month, and thus returns \25/5/92 (as the last Monday in May).

Extrapolate{5, 1,\30th Jan 92, 2,\28th Feb 92, 7,\30th Jul 92}

This series is spotted as be the penultimate day of each month, thus the date \30/05/92 is returned.

Time objects can have a series in arithmetic progression e.g. Extrapolate{10, 1,10:59:20, 2,11:00:30, 3,11:01:40} returns 11:09:50, as each item in the series is 70 seconds after the preceding one.

Geometric series can be spotted, but only if two of the elements provided are sequential within the whole series.  For example, Extrapolate{10, 2,12, 4,108, 5,324} CleanSheet spots that this is the geometric series 4 * 3^N (giving the results 4, 12, 36, 108, 324...), but only because the 4th and 5th items are next to each other in the series; if the 6th item had been used, i.e., Extrapolate{10, 2,12, 4,108, 6,972}, then the series would not have been spotted.

If you provide only one object , e.g. Extrapolate{{1,4},"CleanSheet"}, then Extrapolate returns multiple copies of the supplied object, i.e. {"CleanSheet","CleanSheet","CleanSheet","CleanSheet"], in the same manner as MakeArray.

If you provide just two elements of the series, request an array of values in return, and the two elements can be subtracted, CleanSheet assumes that you wish to obtain an arithmetic series, e.g. Extrapolate{{1,10}, 1,1, 3,3} returns the series {1,2,3,4,5,6,7,8,9,10}.

Note that you can specify that the range should be returned in descending order, via Extrapolate{{10,1}, 1,1, 3,3}, which would return the series {10,9,8,7,6,5,4,3,2,1}.

Extrapolate may also be used on vector and array objects i.e. Extrapolate{{1,5}, 1,{1,2,3}, 2,{3,5,7}, 3,{5,8,11}} will return the series of vectors {{1,2,3},{3,5,7},{5,8,11},{7,11,15}.{9,14,19}}, because each vector is {2,3,4} more than the previous one.

If Extrapolate cannot spot any form of series, and the objects provided are in contiguous order (for example items 2,3,4 are provided, but not 2,7,9), Extrapolate will cycle round the provide objects until the item number requested is reached, e.g. Extrapolate{{1,7}, 1,"Value 1", 2,"Value 2", 3,"Value 3"} will return the array {"Value 1","Value 2","Value 3","Value 1","Value 2","Value 3","Value 1"}.

Please Note that Extrapolate is not a statistical function; It recognises particular types of series, rather than finding the closest series that matches.  If you wish to find the closest matching series, please use the relevant statistical functions, not Extrapolate.


Identity2, Identity3

Identity2 returns a 2 by 2 Identity matrix, while Identity3 returns a 3 by 3 identity matrix.


Curve and Line Fitting - Introduction
Curve and Line Fitting.

The following group of functions deal with fitting lines to a set of points, and evaluating a series via some statistical function.

When you know that a set of points falls roughly along a straight line, use the straight line fit functions; if you know that the points fall roughly along an exponential curve, use an exponential fit function; if you know that the points form a line based on a 'y=ax^2' function, use the square fit functions. If none of the preceding apply, and you know the line is unlikely to fit a simple curve, use the polynomial fit.

Once you have an equation describing the line, you can then calculate, should you want, a wider range of results than the set provided, to calculate a trend.  This can be done be using the returned equation in the Eval{} function.

FitLine	Fits a straight line to data

FitExp	Fits and Exponential Curve to data

FitSqr	Fits an x^2 Curve to data

FitPoly	Fits a Polynomial to data


FitLine
FitLine{{x1,y1},{x2,y2}...}

Fits a (straight) line to a set of x,y points, using least squares fit, and returning an equation object describing the line; this can be reused via the Eval{} function to extend the line.  FitLine takes an array of points, in the form {{x1,y1},{x2,y2}....{xn,yn}}; if you supply two arrays of x & y points, i.e. {{x1,x2,...xn},{y1,y2...yn}}, then FitLine will automatically transpose the arguments for you.

For example, FitLine{{12,5.27},{18,5.68},{24,6.25},{30,7.21},{36,8.02},{42,8.71},{48,8.42}} returns the equation "3.99 + x*0.103", i.e. an equation of the form 'y = c + mx', describing the line.


FitExp
FitExp{{x1,y1},{x2,y2}...{xn,yn}}

FitExp (Fit Exponential Curve) will fit a curve of the form 'y = be^x' to a supplied set of data points, by using least square fitting. As per FitLine, it takes an array of points, and if you provide two lists of X & Y values, i.e. {{x1,x2,...xn},{y1,y2...yn}}, will automatically transpose the values into the required form.

It returns an equation object describing the best fitting exponential curve for the supplied points e.g. for the points {{12,5.27},{18,5.68},{24,6.25},{30,7.21},{36,8.02},{42,8.71},{48,8.42}}, FitExp returns the equation "4.4474914*exp(0.01494128*x)", which may be passed to the Eval{} function to obtain further points on the curve.


FitSqr
FitSqr{{x1,y1}.{x2,y2}...{xn,yn}}

FitSqr fits a curved line of the form 'y = bx^2' to the set of provided data points. Like the other line fit functions, it takes pair of point locations, or transposes an array of X & Y values into points, i.e. {{x1,x2,...xn},{y1,y2...yn}} will be transposed to {{x1,y1},{x2,y2},{x3,y3}...}. The fit is achieved by the least squares method.

It returns an equation object for the line, which may be used via the Eval{} function to produce further points.


FitPoly
FitPoly{{{x1,y1},{x2,y2}...{xn,yn}},order}

The other curve and line fitting functions within CleanSheet may be familiar from other SpreadSheet packages, CleanSheet adds a much more general curve fitting function in FitPoly, which fits polynomial curves.

FitPoly fits a set of points to a polynomial of the form 'y = a + bx + cx^2 + dx^3...";  As per other curve fit functions, it takes a set of points, but these are separated from the last argument, which specifies the order to be used. For example, if MyArray := {{12,5.27},{18,5.68},{24,6.25},{30,7.21},{42,8.71}}, then the call would be FitPoly{MyArray,4} to produce the 4th order equation.

The order may have the values 2 to 14; e.g. If you specify that the order is 2, then FitPoly{} returns an equation of the form 'y = a + bx + cx^2'.  If you do not supply the order, then FitPoly defaults to a third order equation, i.e. FitPoly{MyArray} returns an equation of the form 'y = a + bx + cx^2 + dx^3'. If you attempt to request a polynomial fit of less than 2, FitPoly{} will return an error object, instead of the equation.

FitPoly will accept the point data without indicating the outer array, e.g. FitPoly(MyArray), but if you wish to specify the order to be used you must use the full syntax of FitPoly{MyArray,Order}.

If needed FitPoly will transpose a source array of the form {{x1,x2,x3,x4...},{y1,y2,y3,y4...}} to the correct form {{x1,y1},{x2,y2},{x3,y3}....}.

Note that to fit an N order polynomial, N+1 data points must be provided.  If you request a higher order polynomial than is possible with the supplied number of data points, FitPoly{} will automatically produce a lower order polynomial, of the order N, where N is the number of data points less one.


Mean
Mean{n1,n2,n3...nX}

Mean{} returns the statistical mean of the set of values in the passed array.

All numbers passed are used in the calculation of the mean value, regardless of whether they are separate values or elements of a sub-array. Complex numbers within the list will have the real part included into the mean calculation.

Objects that are not numeric values, e.g. Strings, Equations etc., will not be included when calculating the mean value, e.g. Mean{143,"a",28,193,2938,{123,32}} returns 576.166


Count
Count{n1,n2,{n3,n4}...}

Returns the number of numeric objects in the provided array.All simple numbers are included. String and other non-numeric types will be skipped.

To obtain the number of elements within an array, irrespective of their type, use the Size{} function.


Max
Max{n1,n2,{n3,n4}...}

Returns the maximum value from a list or array containing numeric objects, e.g. Max{1,2,3.45,0.5} returns the value 3.45.


Min
Min{n1,n2,{n3,n4}...}

Returns the minimum value from a list or array containing numeric objects, e.g. Min{1,2,3.45,0.5} returns the value 0.5.


SumSqr
SumSqr{n1,n2,{n3,n4}...}

Returns the sum of the squares of the numeric values provided in the list or array, e.g. SumSqr{143,28,193,2938,{123,32}} returns 8706479.


Sum
Sum {n1,n2,{n3,n4}...}

Sums all the numeric elements within an array and returns a double precision number representing the result.

Sum{100,{1,2,3}} return 100+1+2+3 = 106


Flatten
Flatten{data}

Flatten examines the passed array, and converts it to a list containing each element, i.e. given MyArray := {{123,12.3},"A String",{2+3i,10+6i}} returns {123,12.3,"A String",2+3i,10+6i}, flattening the sub arrays.


Median
Median{data}

Returns the median (middle) value of the range of numbers within the array. This is the statistical median value, thus if you provide an array that contains an even number of numeric elements, then the average of the two values either side of the mid-point is returned, i.e. Median{143,28,193,2938} returns 168 (the median of 143 and 193).


STDev
STDev{data}

Returns the sample standard deviation from a population provided as a list or array, for example, STDev{100,200,300,400,500,600,700,800,900} = 273.86.


STDevp
STDevp{data}

Returns the population standard deviation from a population provided as a list or array, for example, STDevp{100,200,300,400,500,600,700,800,900} = 258.199.


Var
Var{data}

Returns the variance of a population, based on a sample of the population, provided as a list or array, for example, Var{100,200,300,400,500,600,700,800,900} = 75000.


VarP
VarP{data}

Returns the variance of a population, based on the complete population, provided as a list or array, for example, VarP{100,200,300,400,500,600,700,800,900} = 66666.66....


Eval
Eval{Equation,Evaluate_for}

This function evaluates a function for a set of values. It takes an equation object using a single variable, and returns the result(s) for the provided value(s), e.g. if MyFunc := "35.4*x + 12", then Eval{MyFunc,3} will return the value 118.2. You can provide the function as a string rather than an equation object, e.g. Eval{"35*x + 12",3} will again return 118.2

CleanSheet knows that an equation is required and will convert it automatically.

The Equation must of the form f(x) i.e. a function of 'x'. No other variable name is suitable. CleanSheets curve and line fitting functions will return equations of the form y=f(x) so they can be used directly with this function.

If you wish to obtain a range of values, then supply a list of values to be substituted for the variable within the equation, i.e. Eval{MyFunc,{1,2,3}} will return the array of results {47.4, 82.8, 118.2}. Note that because the values to be substituted are provided as an array, the results will be returned in an array form, e.g. Eval{MyFunc,3} returns 118.2, while Eval{MyFunc,{3}} returns {118.2}.

A more complex use of this is to fit a set of points to a line, and then use the returned expression to obtain additional points along the line. For example, if the array MyPoints := {{12,5.27},{18,5.68},{24,6.25},{30,7.21}}, then FitPoly{MyPoints,3} will return the equation [MyFunc :=] '3.866+0.1065x', which can then be used to obtain further results via Eval{MyFunc,{10,15,20}}, which will return the results {5.129,5.469,5.841}, by substitution of the values 10, 15, and 20 for x, in order.


AddSecs
AddSecs{DateTime,Number}

It is sometimes useful to handle a date and time as a composite object; to do this, store the date and time object within consecutive elements of an array, in the order time then date object.  AddSecs{} can then be used to add the supplied number of seconds to the composite date and time, correctly adjusting the composite values as required.  To subtract, simply add a negative value.  For example, given MyDT := {12:05:10,\15th Jan 92}, then AddSecs{MyDT,86465} returns the composite array object {12:06:15,\16th Jan 92}.


AreaPoly
AreaPoly{{x1,y1},{x2,y2}...{xn,yn}}

Given a set of points describing a polygon, AreaPoly{} calculates the area the polygon encloses. This is done via partial rasterisation, and will thus return a double result object approximately accurate to within 0.5%.  The supplied list of points will be transposed into (x,y) pairs if two lists of X and Y points are provided. So an array {{x1,x2,x3...xn},{y1,y2,y3...yn}} will be detected and transposed automatically.

If the points do not describe a closed polygon, then the polygon will be closed automatically.


AreaEllipse
AreaEllipse{{x1,y1},{x2,y2}}

AreaEllipse calculates the area enclosed within an ellipse, returning a double result object. The two arguments provided are any two diagonally opposite corners of the bounding rectangle for the ellipse.


AreaRect
AreaRect{{x1,y1},{x2,y2}}

AreaRect returns the area enclosed by a rectangle, as a double numeric object.  It requires two arguments, giving the points of any two diagonally opposite corners of the rectangle.


AreaPie
AreaPie{{x1,y1},{x2,y2},StartAngle,EndAngle}

AreaPie returns the area of a pie segment, given the point coordinates of any two opposite corners of the ellipse the pie segment is taken from, and the start and end angle.

Note that the start and end angle should passed as Radian values, not in degrees.

The start and end angles are adjusted internally so the ellipse represents a distorted circle.  Diagramatically, this is


InPolygon
InPolygon{{xv,yv},{{x1,y1},{x2,y2}...{xn,yn}}}

InPolygon{} checks to see if a supplied point {xv,yv} lies within or outside the polygon described by the points {x1,y1}...{xn,yn}, returning a boolean FALSE or TRUE result.  InPolygon{} will automatically transpose the points list to (x,y) pairs if they are given as a X-list and Y-list.  If the points do not describe a closed polygon, then InPolygon will automatically close the polygon.


InEllipse
InEllipse{{xv,yv},{x1,y1},{x2,y2}}

Tests if the supplied point {xv,yv} lies within the ellipse whose bounding rectangle is given by the opposite corners {x1,y1} and {x2,y2}, returning a boolean FALSE or TRUE result.


InRect
InRect{{xv,yv},{x1,y1},{x2,y2}}

Tests if the supplied point {xv,yv} lies within the rectangle given by the diagonally opposite corner points {x1,y1} and {x2,y2}, returning a boolean FALSE or TRUE result.


InPie
InPie{{xv,yv},{x1,y1},{x2,y2},StartAngle,EndAngle}

Tests  that the supplied point {xv,yv} lies within the Pie segment of the ellipse bounded by the rectangle having the diagonally opposite corners {x1,y1} and {x2,y2}, covering the segment from StartAngle to EndAngle.  It returns a Boolean FALSE or TRUE result.

Note that the angles are given in Radians.


Statistical Modeling Functions, Introduction
Statistical Modeling Functions.

Within CleanSheet there are a wide range of statistical modeling functions. These functions have all been standardised in their arguments, which may mean that arguments are provided in an order you would not initially expect.

For each modeling function, there are three functions. The density function will calculate the density at a particular point (or the probability of a particular event, where events are discrete items).
The probability function, these are standardised to return the probability up to the supplied point, e.g. the probability 'x<r'. (Note that the this NOT the same as 'x<=r'; the distinction is important when considering discrete probabilities.)
The threshold function, these are effectively the reverse of the probability functions, returning the value of r for which the probability of 'x<r' is specified.

ProbNormal

DensNormal

ThreshNormal

ProbBinomial

DensBinomial

ThreshBinomial

ProbExp

DensExp

ThreshExp

ProbPoisson

DensPoisson

ThreshPoisson

ProbRect

DensRect

ThreshRect

ProbHyperGeo

DensHyperGeo

ThreshHyperGeo

DensChiSqr

ProbChiSqr

ThreshChiSqr

Densf

ProbF

ThreshF

DensGamma

ProbGamma

ThreshGamma

DensT

ProbT

ThreshT


ProbNormal
ProbNormal{r,mean,standard deviation}

Returns the probability for a normal distribution model, i.e. the probability for x<r, given the normal distribution specified by the mean and standard deviation values. For example, if a large number of students take a test, and their resultant scores are normally distributed around the mean value 200, with a variance of 400 [thus the normal standard deviation is sqrt(400)], then the proportion of the students that score less than 250 can be calculated as ProbNormal{250,200,20}, returning the result 0.994 (to three decimal places).

See Also Statistical Modeling Functions


DensNormal
DensNormal{x,mean,standard deviation}

Returns the density of a normal distribution set at a point 'x', given the mean and normal standard deviation of the set.

See Also Statistical Modeling Functions


ThreshNormal
ThreshNormal{p,mean,standard deviation}

ThreshNormal returns the value x for which the probability of x<r is the probability 'p'. Using the same example as ProbNormal{}, then ThreshNormal{0.994,200,20) returns 250.24; Note that there may be a slight error, as in this case, caused by the rounding of the results.

See Also Statistical Modeling Functions


ProbBinomial
ProbBinomial{r,n,p}

Returns the probability of x<r, using the binomial distribution model. Since this is a discrete distribution, the sum of the probabilities up to r is returned, e.g. for r=4 the probability return is the sum of the probabilities for (x=0, x=1, x=2 and x=3) n is the number of trials, r is the threshold value and p is the probability of success.

For example: A machine produces metallic rods. The probability that the length of a rod is outside the required length is 0.1, and if such a rod is found then it must be rejected. For a sample batch of 12 rods, what is the probability that 2 or more will have to be rejected?

This (x < 2) can be calculated as ProbBinomial{2,12,0.1}, which returns an answer of 0.659. This, however, is the probability that fewer than 2 rods are defective; thus to get the probability that 2 or more rods will be defective the result (1-0.659) is required, giving the wanted probability of 0.341.

See Also Statistical Modeling Functions


DensBinomial
DensBinomial{x,n,p}

Returns the density of a binomial distribution set as a point. Since the binomial distribution is discrete, this returns the probability of the particular event actually happening. It requires 'x', the density, 'n', the number of trials, and 'p' the probability. Using the same example as ProbBinomial{}, the probability of exactly two rods failing can be found via DensBinomial{2,12,0.1}, which returns 0.2301.

See Also Statistical Modeling Functions


ThreshBinomial
ThreshBinomial{prob,n,p}

ThreshBinomial calculates the value of r, where the probability of x<r is greater than or equal to prob. The number of trials is given as n, and the probability of success for each trial is p.

Using the example from ProbBinomial, ThreshBinomial{0.65,12,0.1} returns 2, since when r=2, the probability of x<2 is 0.659, which is greater than the limit of 0.65 we are looking for; In effect, when r=2, ProbBinomial{r,n,p} exceeds 0.65.

See Also Statistical Modeling Functions


ProbExp
ProbExp{r,l}

ProbExp{} returns the probability for an exponential distribution of x<r, where 'l' gives the exponential distribution value.

For example: The mean life of an electrical light bulb is 100 hours, and its failure rate against lifetime increases exponentially. What is the probability that a bulb will last less than 60 hours?

The mean of an exponential distribution 'ed' is 1/ed, thus l = 1/100, or 0.01. Hence ProbExp{60,0.01} returns the value 0.45 (to two decimal places) - an almost 50% chance that a bulb will survive less than 60 hours.

See Also Statistical Modeling Functions


DensExp
DensExp{x,l}

DensExp{} returns the density of an exponential distribution of value 'l' at the point 'x'. For example, DensExp{60,0.01} returns 0.00549.

See Also Statistical Modeling Functions


ThreshExp
ThreshExp{p,l}

ThreshExp{} returns the value of x such that the probability of x<r is p (i.e. the reverse of ProbExp{}). The exponential distribution is give by 'l'. For example, ThreshExp{0.45,0.01} returns 59.78 - The slight error (from the 60 hours of our example in ProbExp), is because the value 0.45 was only accurate to 2 decimal places.

See Also Statistical Modeling Functions


ProbPoisson
ProbPoisson{r,a}

Calculate the probability of x<r for a poisson distribution set given by the parameter a.

For example, the probability that a bottle of chemicals produced by a machine will contain some impurity is 1/20. On a sample of 60 bottles, what is the probability that less than 2 bottles will be tainted?

The second parameter, 'a', is given by the expression n*p, where n is the sample size and p the expressed probability, hence the call is ProbPoisson{2,3}, returning the value 0.1992.

See Also Statistical Modeling Functions


DensPoisson
DensPoisson{x,a}

DensPoisson{} returns the density of a poisson distribution set 'a', at the point 'x'. Since this is a discrete probability distribution, it returns the probability of a particular event.

Using the same example as ProbPoisson{}, then the probability of exactly 2 bottles being tainted is DensPoisson{2,3}, which returns the value 0.2240.

See Also Statistical Modeling Functions


ThreshPoisson
ThreshPoisson{p,a}

ThreshPoisson{} returns the value of r for which the probability of x<r is greater than or equal to p, e.g. ThreshPoisson{0.19,3} = 2, since when x = 2, ProbPoisson{x,3} returns 0.224, which is greater than the supplied value 0.19.

See Also Statistical Modeling Functions


ProbRect
ProbRect{r,a,b}

Returns the probability of x<r, based on rectangular distribution, where the probabilities are evenly distributed across the interval a <= x <= b, with the density for points outside the range a to b being zero, e.g. ProbRect{190,100,200} = 0.9.

See Also Statistical Modeling Functions


DensRect
DensRect{x,a,b}

DensRect calculates the density of a rectangular distribution, specified as the range a to b, at point x, i.e. DensRect{50,100,200} returns 0; since the probability range is 100 to 200, then at 50 the probability density is zero, while DensRect{150,100,200} returns 0.01 - note that any value of x falling within the range a to b will return the same value, since the distribution is constant across the range.

See Also Statistical Modeling Functions


ThreshRect
ThreshRect{p,a,b}

Returns the value of r for which the probability of x<r is equal to p, where the probabilities are equally spaced across the range a to b, e.g. ThreshRect{0.5,100,200} returns 150.

See Also Statistical Modeling Functions


ProbHyperGeo
ProbHyperGeo{r,N,n,p}

ProbHyperGeo calculates and returns the probability of x<r for a hyper-geometric distribution set, where N is the population size, n is the sample size and p is the proportion of the population having the property we are searching for (i.e. for the population N, N*p have the particular property we are looking for).

For example, in a population of 100 people, 10% have high blood pressure. If we take a sample of 8 people, what is the probability of less than 3 of the 8 having high blood pressure?

This can be found via the call ProbHyperGeo{3,100,8,0.1}, returning 0.97 (to 2 decimal places).

See Also Statistical Modeling Functions


DensHyperGeo
DensHyperGeo{x,N,n,p}

DensHyperGeo returns the density at point x for the hyper-geometric distribution set. Since hyper-geometric distributions are discrete, it calculates the probability of a particular event. For the example in ProbHyperGeo{}, the probability of exactly 2 people having high blood pressure is DensHyperGeo{2,100,8,0.1}, which returns the result 0.1506.

See Also Statistical Modeling Functions


ThreshHyperGeo
ThreshHyperGeo{P,N,n,p}

Returns the value of r for which x<r is greater than or equal to the supplied probability P. This is the reverse of ProbHyperGeo{}, in that it finds the value of r given the value of x.

For the same example as ProbHyperGeo{}, the result returned is ThreshHyperGeo{0.96,100,8,0.1}, or 3, since when r=3 the probability of x<3 (i.e. for x=0, x=1 and x=2) is 0.97, which exceeds the probability we were looking for.

See Also Statistical Modeling Functions


ProbChiSqr
ProbChiSqr{r,v}

ProbChiSqr{} returns the probability of x<r, for a chi-squared distribution, where v is the degrees of freedom required, e.g. ProbChiSqr{10.645,6} will return 0.90.

See Also Statistical Modeling Functions


DensChiSqr
DensChiSqr{x,v}

Returns the density for the point x on a chi-squared distribution having v degrees of freedom, i.e. DensChiSqr{4,20} returns 11738.7.

See Also Statistical Modeling Functions


ThreshChiSqr
ThreshChiSqr{p,v}

ThreshChiSqr calculates the threshold point at which the probability of x<r is p, for a chi-squared distribution with v degrees of freedom - this is the reverse of ProbChiSqr{}, e.g. ThreshChiSqr{0.9,6} returns 10.645.

See Also Statistical Modeling Functions


ProbF
ProbF{r,v1,v2}

ProbF{} calculates the probability of x<r for an F distribution curve having degrees of freedom v1 and v2; F distributions are used in comparing two chi-squared distributions and hence two degrees of freedom must be supplied. Note that the result is evaluated by numerical means, and may therefore take a large amount of processing time on slower machines.

For example, ProbF{3.29,7,9} returns 0.95 (to two decimal places), indicating that 95% of the area under the F curve is to the left of x=3.29 (and therefore 5% is to the right).

See Also Statistical Modeling Functions


DensF
DensF{x,v1,v2}

DensF{} returns the density for an F distribution curve at the point x, given the degrees of freedom v1 and v2, e.g. DensF{20,8,3} returns 0.001141 (when rounded).

See Also Statistical Modeling Functions


ThreshF
ThreshF{p,v1,v2}

Returns the threshold value of x, where the probability of x<r is p, and the degrees of freedom allowed for the F distribution curve are v1 and v2. This is the reverse of ProbF{}, for example ThreshF{0.95,7,9} returns 3.28, since at x=3.28 95% of the area of the curve is to the left of point x and 5% to the right; the slight error is caused by our rounding the probability to 0.95.

See Also Statistical Modeling Functions


ProbGamma
ProbGamma{r,alpha,beta}

ProbGamma{} returns the probability of x<r for the Gamma curve given by alpha and beta, e.g. ProbGamma{60,1,100} returns 0.45 (rounded to two decimal places).

See Also Statistical Modeling Functions


DensGamma
DensGamma{x,alpha,beta}

Returns the density at point x for the Gamma curve specified by the parameters alpha and beta, i.e. DensGamma{60,1,100} returns 0.00549.

See Also Statistical Modeling Functions


ThreshGamma
ThreshGamma{p,alpha,beta}

ThreshGamma calculates the threshold value r at which the probability of x<r is p, for the Gamma curve given by alpha and beta, e.g. ThreshGamma{0.45,1,100} returns 59.84 (errors being due to the rounding on p).

See Also Statistical Modeling Functions


ProbT
ProbT{r,v}

ProbT{} calculates the probability of x<r for a Student-T distribution having v degrees of freedom, e.g. ProbT{2.447,6} = 0.975.

See Also Statistical Modeling Functions


DensT
DensT{x,v}

Returns the density for a Student-T distribution at the point x, where v gives the degrees of freedom, e.g. DensT{1.2,10} will return 0.185664

See Also Statistical Modeling Functions


ThreshT
ThreshT{p,v}

Returns the threshold point r at which the probability of x<r is equal to p, for the Student-T distribution having v degrees of freedom, e.g. ThreshT{0.975,6} returns 2.447, since 97.5% of the area under the Student-T curve is to the left of 2.447 (and 2.5% to the right).

See Also Statistical Modeling Functions


ChiTest
ChiTest{...}

The Chi-Square Test (Pronounced Ki-Square) is a statistical test used to compare events. It compares observed events with expected events and returns the probability that any mismatch was due to error.

It has two forms, in the first it compares two arrays of data, the observed data set and the expected data set and calculates the Chi-Square result.

In the second it compares a set of co-ordinates with a line or curve equation and return how closely the curve or line represents the data.

In both cases it calculates a ChiSquared variable and then evaluates the probability of the variable's value, using the ProbChiSqr{} function.  The end result is a value in the range 0 to 1, where 0 represents a perfect match, and 1 a total mismatch.

Note that the a ChiTest is only statistically valid when used on results on datasets having 5 or more values - any results obtained using fewer values must be treated with care.

Comparing Observed and Expected Data

In is first form, testing for correlation between two sets of data, the arguments are supplied in the form

ChiTest{{array of observed values},{array of expected values}}

For example: Supposing you are examining the results of a Die to see if it has been weighted. If the die is thrown 60 times, an equal probability is expected for any face if the die is correct, hence you would expect each face to occur an equal number of times (i.e. 10 lots of 1, 10 lots of 2...10 lots of 6).  Thus the expected set of results would be given as {10,10,10,10,10,10}.

If you actually got the results {15,7,4,11,6,17}, for each of the faces 1 through 6, then you can see that the results are not what was expected, but are they different enough to say the die is weighted.

Given that a result of 95% or greater would meet our suspicions that the die is weighted, then evaluating the results via

ChiTest{{15,7,4,11,6,17},{10,10,10,10,10,10}}

returns a value of 0.98, showing that the die can be considered crooked.

Goodness of Fit Test

For the second form of use, the ChiTest{} function can check the goodness of fit of the data points to a curve or line equation (as returned by FitLine, FitSqr, etc.).  In this form the arguments are

ChiTest{{Array of vertices},Equation}

The equation can be provided as an equation object that has previously been returned from one of the line fitting function, or a string version of an equation to be used, which will be converted into an equation object before use. A result closer to zero indicates a better fit. Zero itself would be a perfect fit, results closer to 1 represent a bad fit.

The equation is always assumed to be a function of X.

For example.  You have the equation "10*x+5" and want to test how this equation fits a set of data points.  The call to ChiTest will be of the form

ChiTest{{{2,25},{5,54},{8,78},{3,35},{6,68}},"10*x+5"}

Note the brackets around the vertices - {{2,25},{5,54},{8,78},{3,35},{6,68}} - showing that this is an array of  observed {x,y} points, not five parameters to ChiTest{}.

ChiTest{} will calculate how far the observed y values differ from the expected y values (as evaluated by the equation), and in this case return the result 0.05313, showing a very close fit.

As with the line and curve fitting functions, if you supply the vertices as two lists of x and y points, then the lists will be transposed into point pairs automatically.


SparseFact
SparseFact{{a0.a2,a1},{b0.b2,b1}}

SparseFact{{a,b,c...},{z,x,y...}} calculates the factorial for a series of  the form (a! * b! * c!...)/(z! * x! * y!...), which normally exceed the limits of calculation, returning some form of overflow error.

For example, the calculation of 400!/400! has the result of 1, but attempting to calculate 400! will cause most systems to overflow.  In the same manner, (60! * 60! * 60! * 60! * 60!)/(60! * 60! * 60! * 60! * 60!) again has the result of 1, and although 60! can be calculated without error, 60!^5 will again return an overflow error.

These problems are common within statistical functions (Hyper Geometric distributions for example use this function to avoid overflows).

If you wish to calculate a single factorial ratio, you can omit the enclosing curly brackets for each list, e.g. SparseFact{100,99}, which returns the value 100, or a list of up to 32 values for each argument list, e.g. SparseFact{{100,120,130},{99,119,131}} will calculate (100! * 120! * 130!)/(99! * 119! * 131!),  which returns the result 91.6 - note that this calculation will only take 1 multiplication and 1 division, as it reduces to 100 * 120 / 131.


Combinations
Combinations{n,r}

The Combinations{} function returns the number of combinations of r from n, e.g. Combinations{4,2} returns 6.

This function uses the SparseFact{} function, to avoid numeric overflow during calculation of the factorial values.


Integrate
Integrate{equation,lower,upper,resolution}

Integrates a passed equation, which can be an equation object or string representation of an equation (which will be converted to an equation), for x, to a given % resolution between the supplied lower and upper bound, by use of numerical methods.

The optional % resolution is expressed as a value between 0 and 1, for example, 0.001 means that the errors must be less than 0.1%; if the resolution parameter is omitted, then it is assumed to have a default value of 0.005 (0.5%).  Returned results will usually be more accurate than the requested resolution; at the very least they will be within the supplied resolution.

Functions that tend to infinity within the lower and upper bounds will not be integrated.

For example, Integrate{"exp(x)",0,100,0.05} returns 2.722e43 (the correct value is 2.688e43) i.e. the answer is within 5%, while Integrate{"exp(x)",0,100} gives 2.69039e43, i.e. the answer is within 0.5%.

There are certain circumstances under which this function will return incorrect results. If an equation behaves chaotically at close resolutions and is stable at coarse resolutions, then this function will fail.


Annuity Functions, Introduction
Annuity functions.

These functions listed below refer to annuities, or regular series of payments made over time; this includes things like loans, investments, savings, etc.

They have equivalents in most other spreadsheets, so they should not be unfamiliar.

See Also

FV	- Future Value

PV	- Present Value

PMT	- Payments

IPMT	- Interest Payments

PPMT	- Principal Payments

NPER	- Number of Periods

RATE	- Interest Rate


FV
FV{rate,nper,pmt,pv,type}

The last 2 parameters can be omitted and if this is done, they are assumed to be zero.

FV{} returns the future value for an investment, that is -  how much will be returned  at a certain future point in time. The Parameters are:

Rate	of return, expressed as a value between 0 and 1 or a % (e.g. 0.1 and 10% both represent the same rate),

NPer	the number of periods over which payments are made.

PMT	the amount of each payment

PV	the present value of the investment,

Type	and a payment Type of 1 (beginning) or 0 (end), indicating if the payments are made at the beginning or end of each period.

Consider the following example. You have an investment plan where you pay £200 per year at a return rate of 8% per annum. The present value of the investment is £600. What would be the value of the investment after four years, if the payments are made at the end of each year?

Calculating this manually, the sequence is

Initial value £600

Interest added after year 1 at 8%, giving £648

Payment at year 1 of £200, giving £848

Interest added after year 2, giving £915.84

Payment at year 2 of £200, giving £1115.84

Interest added after year 3, giving £1205.11

Payment at year 3 of £200, giving £1405.11

Interest added after year 4, giving £1517.16

Payment at year 4 of £200, giving £1717.16

which is far more laborious than FV{8%,4,-200,-600,0} (returning 1717.16).

Note that the payment and initial value are supplied as negative values, since payments are, by convention (and from the point of view of cash in your hand), given as negative values, while receipts are positive.

A second example could be as follows. What is the future value after 3 years of an investment returning 12% per annum, where you pay £100 per month? This can be calculated via

FV{12%/12,36,-100}, returning 4307.69

The interest rate is specified as 12%/12, since the interest rate is given per annum, but we need to know it on a per-month basis. Likewise the number of periods is given in months, rather than years. Since there is no initial capital to the investments, and payments are made at the end of each period, the last two values can be omitted and allowed to default to zero.


PV
PV{Rate,Nper,Pmt,Fv,type}

The last 2 parameters can be omitted and if this is done, they are assumed to be zero.

PV{} is the converse to FV{}; given a known future value, you can determine the present value of an investment at a point in time. The parameters required are:

Rate	expressed as a value between 0 and 1 or a % (e.g. 0.1 and 10% both represent the same rate),

NPer	the number of periods over which payments are made,

Pmt	the amount of each payment,

Fv	the future value of the investment, and a payment

Type	1 or 0,indicating if the payments are made at the beginning (1) or end (0) of each period.

For example. You wish to purchase a car, using a loan, and can afford to pay back the loan at £100 per month. If interest rates are currently at 14% per annum, and you wish to have paid the loan off completely at the end of 3 years, what is the maximum you can borrow? This can be found by

PV{14%/12,36,100}, returning -2925.89

Notice that the interest rate and the number of periods must agree. Here the interest rate has been divided by 12, since the number of periods is given in months, not years.

Given the above requirements, you could therefore afford a car of just under £3000.


PMT
PMT{rate,nper,pv,fv,type}

The last 2 parameters can be omitted and if this is done, they are assumed to be zero.

PMT{} calculates the monthly payments required to support the repayment of a loan, or to support a particular return on an investment.

Rate	of return, expressed as a value between 0 and 1 or a % (e.g. 0.1 and 10% both represent the same rate),

Nper	the number of periods over which payments are made

Pv	the present value of the investment

Fv	the future value

Type	and a payment Type of 1 or 0, indicating if the payments are made at the beginning (1) or end (0) of each period.

Having been offered a loan of £8000, over two years, at a rate of 8% per annum, how much will you have to pay each month to clear the loan? This can be found via

PMT{8%/12,24,8000}, returning -361.82

giving you repayments of £361.82 per month (for a total of £8683.68). Since we want the future value of the loan to be zero, and pay at the end of each month, the last two arguments can be skipped and allowed to default to zero.

Note that the result was negative, indicating money going out.


IPMT
IPMT{rate,per,nper,pv,fv,type}

The last 2 parameters can be omitted and if this is done, they are assumed to be zero.

IPMT{} returns the interest portion of a payment made at a particular point during an investment or loan; contrast this against PMT{}, which returns the whole payment figure. The parameters are:

Rate	of return, expressed as a value between 0 and 1 or a % (e.g. 0.1 and 10% both represent the same rate),

Per	the period for which the interest portion is wanted,

NPer	the number of periods over which payments are made,

Pmt	the amount of each payment,

Pv	the present value of the investment,

Fv	the known future value,

Type	and a payment Type of 1 or 0, indicating if the payments are made at the beginning (1) or end (0) of each period.

Again, using your loan of £8000 over two years at 8% per annum, how much of the 3rd repayment is interest? How much of the 23rd payment is interest? These values can be found via

IPMT{8%/12,3,24,8000}, returning -49.21, and

IPMT{8%/12,23,24,8000}, returning -4.78


PPmt
PPMT{rate,per,nper,pv,fv,type}

The last 2 parameters can be omitted and if this is done, they are assumed to be zero.

PPMT{} returns the principal portion of a payment made at a particular point during an investment or loan.

Contrast this against PMT{}, which returns the whole payment figure, and IPMT{}, which returns the interest portion of the payment.

Rate	of return, expressed as a value between 0 and 1 or a % (e.g. 0.1 and 10% both represent the same rate),

Per	the period for which the interest portion is wanted

Nper	the number of periods over which payments are made,

Pmt	the amount of each payment,

Pv	the present value of the investment,

Fv	the known future value,

Type	a payment Type of 1 or 0, indicating if the payments are made at the beginning (1) or end (0) of each period.

Again, using your loan of £8000 over two years at 8% per annum, how much of the 3rd repayment is paying off the loan? How much of the 23rd payment? These values can be found via

PPMT{8%/12,3,24,8000}, returning -312.61, and

PPMT{8%/12,23,24,8000}, returning -357.04


Nper
NPer{rate,pmt,pv,fv,type}

The last 2 parameters can be omitted and if this is done, they are assumed to be zero.

NPer{} returns the number of periods it will take to pay a loan off, or the number of periods needed for an investment to reach a certain level.

Rate	of return, expressed as a value between 0 and 1 or a % (e.g. 0.1 and 10% both represent the same rate),

Pmt	the amount of each payment,

Pv	the present value of the investment,

Fv	the known future value,

Type	and a payment Type of 1 or 0, indicating if the payments are made at the beginning (1) or end (0) of each period.

For example. On a loan of £8000, paid back at £200 per month, with an interest rate of 12% per annum, how many months will it take to repay the loan? This can be calculated as
NPer{12%/12,-200,8000}, returning 52 (months)

An investment is being made at £200 per month at an interest rate of 8%; how many payments would be required before the investment exceeds £2000?
NPer{8%/12,-200,0,2000}, returning 10 (months).

Note that the final value is given as a positive number, since it is a sum of money you will receive at the end of the investment.

NPer{} always returns an integer number for the number of periods, but the final payment on a loan may be less than the full amount paid in preceding months, or the final value of an investment may be slightly more than the value you wanted the investment to reach.


Rate
Rate{nper,pmt,pv,fv,type}

The last 2 parameters can be omitted and if this is done, they are assumed to be zero.

Rate{} returns the rate of interest being paid on a loan, or the return being made on an investment.

NPer	the number of periods over which the annuity runs

Pmt	the payments being made

Pv	the know present value

Fv	the known future value

Type	indicating if payments are being made at the end (zero) or beginning (one) of each period.

Consider the examples below.

You borrow £9000 from a bank, agreeing repayments of £800 per month over a one year period. What is the monthly rate of interest being paid? This can be found as

Rate{12,-800,9000}, returning 0.01007, or 1.007% per month.

Note that the repayments are negative values (money paid out), while the sum leant is positive (money received).

In another example, you invest £600 each month for 12 months and at the end of this time have an investment of £9000. What was the monthly rate of return on your investment? This is given by

Rate{12,-600,0,9000}, returning 0.039, or 3.97% per month.

CleanSheet calculates the interest by an iterative method, and will return a result between 0 and 10 (i.e. 0% to 1000%). If the interest falls outside this range, the CleanSheet will return a parameter error. Note that a negative value of interest can also be returned; consider a loan, where the repayments will not be enough to service the loan unless the interest rate is negative i.e. the loan company is paying you to borrow money from it.Do not ignore the sign of the result.


SLN
SLN{cost,salvage,life}

This is the simplest form of depreciation function within CleanSheet - straight line depreciation - where the value of the asset falls at a fixed rate throughout its life.

cost	The initial cost

salvage	The Salvage price at the end of life

life	The lifespan

For example, the cost of a machine is £5000, and sold for scrap at the end of four years, it might fetch £100. By how much is the machine devalued each year if it is depreciated by straight line depreciation?
SLN{5000,100,4}, returning 1225

Note that all arguments to SLN{} are positive.


SYD
SYD{cost,salvage,life,period}

SYD{} calculates the sum of years digits depreciation; this allows more of an asset's value to be depreciated in the early years of its life.

cost	initial cost

salvage	final salvage value

life	its lifespan

period	the period to calculate for

SYD{} calculates the depreciation for one period unit only, e.g. if you request the period 1, then the depreciation for the period 0 to 1 is returned; if you supply a period of 2.5, then the depreciation for the period 1.5 to 2.5 is returned.

For example, what is the depreciation for the 3rd period of a £30000 machine over 10 years, having a salvage value of £1000?

SYD{30000,1000,10,3}, returning 4218.18 (the depreciation for the third year).

By contrast, the depreciation for year 9 will be SYD{30000,1000,10,9}, or 1054.55.


DDB
DDB{cost,salvage,life,period,optional_factor}

DDB{} calculates the depreciation on an asset using the double-declining balance method; this declines assets more in the earlier than later years, the rate of depreciation in early years being controlled by a declination factor - the higher the factor value, the faster the depreciation.

cost	initial cost

salvage	the salvage price at end of life

life	the lifespan

period	the period to return information for

optional_factor	the factor to decline by

If you omit the declination factor, then a default value of 2 is used - hence double declining depreciation.

For example, You purchase a machine for £10000, to be completely devalued over 5 years, using the double-declining method. What is the depreciation for years 1 and 5?

DDB{10000,0,5,1}, returning 4000, and

DDB{10000,0,5,5}, returning 518.40


VDB
VDB{cost,salvage,life,start,end,factor,noswitch}

VDB{} is a combination of DDB{} and SLN{} - It starts by calculating the depreciation using the double-declining balance method, but can optionally switch to using straight line depreciation when this is faster than double-declining.  It can also calculate the depreciation for a partial period (while DDB{} can only depreciate for a whole period).

cost	initial cost

salvage	salvage price

life	lifespan

start	the start of the period to analyse

end	the end of the period to analyse

factor	the factor used for DDB

noswitch	TRUE if must not switch to SLN

The last two parameters are optional, factor, if omitted, defaults to 2 for double declining balance and noswitch defaults to FALSE to allow the calculation to switch to straight-line depreciation if this is quicker.

For example, you are depreciating a machine, bought for £2400, to a salvage value of £300, over 10 years. The maximum depreciation allowed by local tax laws is 1.5x.  If you machine was bought in the last quarter of the financial year. what is the depreciation for this first period.

VDB{2400,300,10,0,0.25,1.5,0}, returning 95.56.


IRR
IRR{Value1,Value2,...,ValueN}

IRR{} returns the internal rate of return for a series of cash flows, where Value1, Value2, ValueN are the cash flow values spaced at equal time periods. Negative cash flow indicates monies paid out, and positive monies received.

Consider the purchase of a boat for tourism. Your cash flow amount may look like this:

Year 0	-35000	Purchase

Year 1	4000	Income from year 1

Year 2	-6000	Income of 2000, plus 8000 refurbishment costs

Year 3	8300	Income for year 3

Year 4	7200	Income for year 4

Year 5	5400	Income for year 5

Year 6	17000	2000 Income, plus 15000 from boat sale

If we had invested the money instead, what would the equivalent interest rate of return have been?

IRR{-35000,400,-6000,8300,7200,5400,17000}, returning 0.005326, or 0.5%

IRR{} needs at least one positive and one negative value in the list of cash flow values, otherwise the % rate would be calculated as infinite.

The % rate is calculated by an iterative method, and returned as a value between -0.99999 and +9.9999 (i.e. nearly -100% to +1000%); if the value returned is either of these limits, then the result cannot be taken as reliable.


NPV
NPV{rate,{Value1,Value2,...,ValueN}}

NPV{} returns the net present value for a series of cash flows. It requires the discount rate for each period, and the list of cash flows, spaced in equal time periods.

If a boat costs £25000 to buy, and over the next five years you receive income of £3000, £4000, £3500, £4400 and £19000 (£2000 income plus £17000 from its sale). When you bought the boat, there was the alternative of investing the £25000 at 9% per annum return. Have you been better off by investing in the boat?

NPV{0.09,{3000,4000,3500,4400,19000}} = 24287.40

This is less than the £25000 you started with, therefore the boat was a better investment.

As a second example, you are given a trust fund, into which you deposit £2000, £2000, £2330, £1000 and £7000 over a five year period. If the fund increases by 8% per annum, and at the end of five years is worth £28000, what was the it originally worth?

NPV{8%,{2000,2000,2330,1000,7000}}, returning £10915.30


SAL
SAL{Pv,{Rates},{Payments},Fv,NPer}

The annuities functions will be familiar to users of other spreadsheet packages, which all have a similar range of functions.CleanSheet has, however, a single function that encapsulates all of the above financial functions into one, giving a more powerful and consistent way of obtaining results for a loan, savings or investment calculation. This function also supports uneven payments and uneven interest rates.

Parameters:

Pv	Present Value

{Rates}	Rate(s) of interest

{Payments}	Payment(s) made

Fv	Future value

NPer	Number of periods

If Rates is a single value, then it is constant, if it is an array of values then it is the rate varies.

Similarly if Payments is a single value, then it is constant, if it is an array of values, then it varies.

If the {Rates} or {Payments} are provided as a list of values, then NPer can be omitted, the number of periods then being implicitly defined by the number of entries in the {Rates} or {Payments} lists, e.g. if {Rates} is {10%,12%,13%,9%,8%,11%}, then by implication NPer is 6 because you have specified the rates for 6 periods.

If {Rates} or {Payments} all have the same value for each period, then a single numeric value can be used, instead of a list, i.e. SAL{null,10%,...}, rather than SAL{null,{10%,10%...},...}.

When you do this, you are not implying a number of periods, but you are implying that the rates or payments are constant.

SAL{} returns an array of answers, the first five of which are the same as the calling values.

In effect, you provide what you know and, provided there is enough information, SAL fills in the gaps.

The return is and array of the form:

{Pv,{Rates},{Payments},Fv,NPer,{PIn},{PAp}}

The additional two returned lists are {PIn}, the periodic interest charged on a loan, or returned on an investment, and {PAp}, the amount of each period's payment going to paying off the principal. Note that {Rates} and {Payments} are always returned as lists, even if just a single numeric is used in the call.

So what exactly does it calculate?

The benefit of SAL{} is that you provide whatever values you know, using Null for an unknown item, and SAL{} will then attempt to calculate the missing values.  This is best shown by some examples.

Example #1 - You borrow £8000 from a bank at 1% monthly interest. If you repay £200 each month, how much of the payment made in the 5th month is paying off principal, and how much the interest?

SAL{8000,1%,-200,0}[6][4], returning -124.87

This can be found by giving the present value as 8000 (positive being monies received), an interest rate of 1% (which is constant, so a single value can be used), repayments of -200 (negative means money out), and a future value of 0 (since we wish to pay the loan off). NPer is omitted, since we don't know how long the loan is; SAL{} will calculate the correct value internally.

The [6][4] indexes into the returned value from SAL{}, selecting first the 6th element, which is the list of payments being allocated to principal repayment (the PAp array), and then from this list the 4th element, giving the allocation for the required period - Don't forget that arrays start at element 0, so element 4 is the 5th entry.

By implication, if £124.57 is going to pay the principal in the 5th period, then £200 - £124.57, or £75.13, is the portion covering interest repayment.

Example #2 - You borrow another £8000 from the bank, at 1% per month interest, and agree to pay back at the rate of £1000 per month for 8 months. Due to cash flow problems, however, you skip three payments. What effect does this have on your repayments?

SAL{8000,1%,{-1000,-1000,-1000,0,0,0,-1000,-1000},null}

Note that since varying amounts are repaid, the payments must be given as a list, with the three missed payments having a value of zero. NPer is implicitly defined from the number of elements within the payments list - 8 elements in the array implies 8 periods.

Listing out the returned answers, you get:

Initial value	8000

Interest rates	{0.01,0.01,0.01,0.01,0.01,0.01,0.01,0.01}

Repayments	{-1000,-1000,-1000,0,0,0,-1000,-1000}

Future value	-3469.19

Periodic interest	{-80.00,-70.80,-61.51,-52.15,-52.64, -53.17,-53.70,-44.24}

Principal repayments	{-920,-929.20,-938.49,0,0,0,-788.36,-955.76}

Thus, just before the skipped payments, £938.49 of the £1000 is going to pay principal, while just after, it has dropped to £788.36, much more of the repayment is going to pay off accumulated interest.

Notice also that there is still £-3469.19 still to pay.

See Also - SAL Further Examples


SAL Further Examples

Example #3 - You wish to borrow £8000 and repay it over 8 months, at an interest rate of 1% per month. What will your monthly repayments have to be?

SAL{8000,1%,null,0,8}[2], returning {-1045.52...-1045.52}

i.e. 8 payments of £1045.52. Note that the source {payments} array is supplied as Null, and the returned payments array is subscript [2] of the answer from SAL{}.

Example #4 - You have taken out the £8000 loan from example 3. However, after the 3rd month the base interest rates go up from 1% to 5%. What do the repayments become?

SAL{8000,{1%,1%,1%,5%,5%,5%,5%,5%},{-1045.52,-1045.52,-1045.52},0}[2], returning

{-1045.52,-1045.52,-1045.52,-1172.05,-1172.05,-1172.05,-1172.05-1172.05}

i.e. the payments go up by £126.53 from £1045.52 to £1172.05.

Example #5 - You invest £400 per month, at 1% interest per month. How much does your investment return after 8 months?

SAL{0,1%,-400,null,8}[3], returning the future value £3314.27.

Example #6 - You invest £8000 over 10 years at 9% per annum interest. At the end of the period, you wish the capital to have doubled from £8000 to £16000. Can you draw an income from the investment and still double the capital, and if so how much income?

SAL{-8000,9%,null,16000,10}[2], which returns the payments list {193.44,...,193.44}

Note the initial investment value is negative, since you have paid money out, the {Payments} is null, since we want SAL{} to calculate and return the payments, and the future value is positive, since you want to be paid £16000 at the end.

Since the values returned in the payments list are positive (i.e. money coming in), the answer is yes, you can double the capital, and have an income of £193.44 per year; if the values in the payments list had been negative, then taking the income would mean that the capital would not double to £16000.


Number formatting Characters

When CleanSheet displays numbers, it does so in a defined format. If the standard defined formats are unsuitable, then CleanSheet allows you to add your own user defined formats. You can also use these format strings of characters with the make{ } function.

The formatting characters available are:

b	Bracket a number if negative, otherwise do nothing

B	Bracket a number if negative, else substitute spaces

N	Display a number grouped into thousands, this displays the section before or after a decimal point and will include a leading minus sign if negative.

n	Display a regular number, with a leading minus sign if b, B, S or s is not specified

S	Show a minus sign if negative, otherwise substitute a space

s	Display a minus sign if negative, otherwise nothing

9	Show a single digit, or a space character if a leading zero

0	Show a digit or nothing if a leading zero

.	Place a decimal point here, the decimal point is only displayed if there is anything to the right

E	Display the exponent here with an E

e	Display the exponent here with an e

X	Display the exponent if there is one with an E character

x	Display the exponent if there is one with an e character

*	Separates multi-part numbers, such as complex numbers

/	Display as a fraction if practical

%	Multiply by 100 before displaying - percentage

A	Must be before any numbers, sets AM/PM display on time objects

a	Must be before any numbers, sets am/pm display on time objects

!	Surrounds literal text e.g. !Pounds Sterling!


Date Formatting Characters

When defining user defined date formats, or specifying the format string for a make{} conversion function, the following codes are used.

%d	The day of the month 1,2....20,21...

%e	The day of the month with st, nd etc. 1st, 2nd...

%E	The day of the month with ST, ND etc. 1ST, 2ND...

%m	The month in full, January February, March....

%M	The month in capitals JANUARY, FEBRUARY, MARCH...

%a	The month in short form Jan, Feb, Mar...

%A	The month in short form capitals JAN, FEB, MAR...

%n	The month as a number , 1,2,3...11,12

%N	The month as a number, same as %n

%y	The year in full, 1992, 1993, 1994..

%Y	The year in short, 92, 93, 94, 95

%w	Day of week, Monday, Tuesday, Wednesday...

%W	Day of week, MONDAY, TUESDAY..

%s	Day of week short form, Mon, Tues, Wed...

%S	Day of week short form Capitals MON, TUE, WED...

And other characters are taken literally.

Example.

%d/%n/%Y	 is 14/2/69


Title

Introduction

Objects Affected


Row Column Size Dialogue
Row Column Size

Introduction

This dialogue sets the number of rows and columns in a table, or graph.

If you are setting the row/column size for an output table, you should note that 'Redimension to Fit Data' option on the 'Output Table Settings' dialogue may cause the tables size to change when the sheet is next recalculated. See Output Table Settings.

Objects Affected

Input Table

Output Table

Output Density Graph

Input Density Graph


Number Formats
Number Format

Introduction

This dialogue sets the format for displaying numbers. There are many predefined formats, and if these are unsuitable, you can add your own.

To add your own, you need to be familiar with the Number Formatting Codes.

Click on any part of the dialogue that you require help on.

Defining your own Number Formats

Enter the string representing your format in the Format Style section.

Enter the Name to call your format in the Format Name section.

Check the samples window to see your format is reasonable.

Click on ADD to add the style to the list.

Deleting a Defined Number Format

Click on the Number format to remove.

The Name and Format text will appear in Format Name and Style

Delete will be disabled if a system style is selected.

Click on Delete

Objects Affected

Input Table

Tumbler

Output Table

Line/Column/Area Graph

Output Density Graph

Input Density Graph

Pie Chart

Segment Chart

Line/Bar/Area Chart

Polar Graph

Polar Input Graph

Polar Calculation Graph

Hard Copy Object

Filing Clerk Object

Slider

XY Scatter Graph

XY Scatter Input

XY Scatter Calculation

3D Graph

Converter


Predefined Number Formats

This is a list of predefined and user defined formats for numbers. Any formats you have previously added appear in this list.

Click once on any of these formats to select it as the format.

Double click on any of these formats to select it and close the dialogue.


Format Name

The format name simply helps explain what the format is for. It does not appear anywhere else and does not have any special purpose.


The Format Style

The format style specifies the actual formatting characters that control how the number will be displayed. If you enter a format that is already specified then its name will be selected from the predefined list.


Add

Adds the number format whose name is given by Format Name and whose style is given by Format Style to the list of formats.

This list is saved with CleanSheet.


Delete

Deletes the selected number format from the list.

You cannot delete system defined number formats.


Samples

The display is 6 samples representing your current number format. If any of these samples are missing, then it is because the format you have selected cannot display that number, usually because the number is too big for the format.


Date Format Dialogue
Date Format

Introduction

The Date Format dialogue sets the style that CleanSheet uses when displaying dates within an object. There are many predefined formats, and when these do not suffice, you can add new formats to the list.

To add your own, you need to be familiar with the Date Formatting Characters.

Click on any part of the dialogue that you require help on.

Defining your own Date Formats

Enter the string representing your format in the Format Style section.

Enter the Name to call your format in the Format Name section.

Check the samples window to see your format is reasonable.

Click on ADD to add the style to the list.

Deleting a Defined Date Format

Click on the Date format to remove.

The Name and Format text will appear in Format Name and Style

Delete will be disabled if a system style is selected.

Click on Delete

Objects Affected

Input Table

Tumbler

Output Table

Converter

Hard Copy Object

Filing Clerk Object

Slider


Predefined Number Formats
Predefined Date Formats

This is a list of predefined and user defined formats for dates. Any formats you have previously added appear in this list.

Click once on any of these formats to select it as the format.

Double click on any of these formats to select it and close the dialogue.


Format Name

The format name simply helps explain what the format is for. It does not appear anywhere else and does not have any special purpose.


The Format Style

The format style specifies the actual formatting characters that control how the number will be displayed. If you enter a format that is already specified then its name will be selected from the predefined list.


Add

Adds the date format whose name is given by Format Name and whose style is given by Format Style to the list of formats.

This list is saved with CleanSheet.


Delete

Deletes the selected date format from the list.

You cannot delete system defined date formats.


Samples

The display is 3 samples representing your current date format.

If you are entering your own date formats, look at the date format samples to check that the results are reasonable.


Time Format Dialogue
Time Formats

Introduction

When CleanSheet displays time objects, this dialogue is used to set the format that the time object will be displayed in.

There are only 4 combinations of time display and this dialogues covers them all, so there is no need to have user defined time formats.

Click on any part of the dialogue you need help on.

Objects Affected

Input Table

Tumbler

Output Table

Converter

Hard Copy Object

Filing Clerk Object

Slider


24 Hour Clock

When this is chosen, the time format runs from 00:00:00 (Midnight) to 23:59:59 (1 second to midnight).


12 Hour Clock

When this is chosen the time format runs from 00:00:00am through 12:00:00pm to 11:59:59pm with an am/pm indication.


Display Seconds

Displays the seconds if selected, if this is not selected only hours and minutes are selected.


Sample Window

Displays 4 samples of the resulting time format.


Complex Number Format Dialog
Complex Number Format

Introduction

The Complex Number Format dialogue sets the style that CleanSheet uses when displaying complex numbers. There are many predefined formats, and when these do not suffice, you can add new formats to the list.

To add your own, you need to be familiar with the Number Formatting Characters.

Click on any part of the dialogue that you require help on.

Defining your own Complex Number Formats

Enter the string representing your format in the Format Style section.

Enter the Name to call your format in the Format Name section.

Check the samples window to see your format is reasonable.

Click on ADD to add the style to the list.

Deleting a Defined Complex Number Format

Click on the Complex Number format to be removed.

The Name and Format text will appear in Format Name and Style

Delete will be disabled if a system style is selected.

Click on Delete

Objects Affected

Input Table

Tumbler

Output Table

Converter

Hard Copy Object

Filing Clerk Object

Slider


Predefined Complex Number Formats

This is a list of predefined and user defined formats for complex numbers. Any formats you have previously added appear in this list.

Click once on any of these formats to select it as the format.

Double click on any of these formats to select it and close the dialogue.


Format Name

The format name simply helps explain what the format is for. It does not appear anywhere else and does not have any special purpose.


The Format Style

The format style specifies the actual formatting characters that control how the complex number will be displayed. If you enter a format that is already specified then its name will be selected from the predefined list.


Add

Adds the complex number format whose name is given by Format Name and whose style is given by Format Style to the list of formats.

This list is saved with CleanSheet.


Delete

Deletes the selected complex number format from the list.

You cannot delete system defined complex number formats.


Samples

The display is 4 samples representing your current complex number format.

If you are entering your own complex number formats, look at these complex format samples to check that the results are reasonable.


Alignment Dialog
Alignment of Text

Introduction

The alignment dialogue sets the text alignment for tables objects within CleanSheet. This is distinct from Content Alignment, which is for aligning blocks of text.

Click on any part of the dialogue you need help with.

The Align to decimal point, aligns to 1/3rd in from the left, 1/3rd in from the right or the center and as such it may clip text at the edge of the box.

Objects Affected

Input Table

Output Table

Hard Copy Object

Filing Clerk Object


Left Align Text

Aligns text to the left edge of the box it is displayed in, or aligns a decimal point to 1/3rd in from the left edge if the Align to Decimal Point button is selected.


Right Align Text

Aligns text to the right edge of the box it is displayed in, or aligns a decimal point to 1/3rd in from the right edge if the Align to Decimal Point button is selected.


Centre Align Text

Aligns text to the centre of the box it is displayed in, or aligns a decimal point to the centre of the box, if Align to Decimal Point is selected.


Align to Decimal Point

Alters the alignment so that decimal points within a column are aligned. The decimal point is aligned either to a third in from the left, the centre or a third in from the right, depending on the alignment selected.


Samples

Some samples of the alignment are shown here.


Wrap

Wraps the text to a form a mult-line entry. Notice that when this is done, decimal point alignment is ignored.


Border Style Dialog
Border Style

Introduction

The border style dialog, sets the style of the border around selected areas of a grid. Since it operates only on selected areas, this dialogue only appears on the menu when in Use mode.

Notice that if you select a group of cells and apply a border to them, the border goes around the cells, rather than forming a grid.

Click on any item in the dialog that you need help on.

To set the Style of the Border Around a Group of Cells

Select the cells within the object to style.

Select Border from the Object menu.

This above dialog appears

Select the sides of the border to draw

Select the colour of the border

Select the line style of the border

Select OK

Objects Affected

Input Table

Tumber


If selected, draws the top line of the box around the selected area.


If selected draws the left edge of the box.


If selected draws the bottom edge of the box.


If selected draws the right edge of the box.


Solid Border


Dotted Border


Dashed Border


Thick Border


Colour

The colour of the border. This must be a solid colour from the pallette, since the border is draw as a line.


Sample Window

Click on a line to switch it on, or click in the centre to switch on all four edges.


Help on the specified dialogue


Grid Style Dialog
Grid Style

Introduction

The grid style dialogue, sets the line-style and grid size for grid objects such as the Input table. It appears only in Edit Mode.

If the select object has multiple -different sized columns or rows, then the column or row size appears blank. If it is left blank, then the size remains unchanged.

Click on the dialogue item you want help on.

To Change the Grid Style of an Object

Select the Object

Select  the Grid Style Menu

This Dialog appears

Select the Line Style Required

Select the Grid Spacing

Check the Sample window looks reasonable

Select OK

The units that the grid spacing are measured in by default depends on the system of measurement set within Windows Control Panel. You can however, enter lengths in any unit you like.
Simply enter the length and follow it with cms - centimeters, pts - for Points, Inches - for Inches or mms - millimeters. Following the length with one of these unit names overrules the default units of measurement.

Objects Affected

Input Table

Output Table

Line/Column/Area Graph

Output Density Graph

Input Density Graph

Line/Bar/Area Chart

Hard Copy Object

XY Scatter Graph

XY Scatter Input

XY Scatter Calculation


Off - Grid is hidden


Dashed


Dotted


Dash Dot


Dash Dot Dot


Solid


Grid Spacing

To change the grid spacing, enter the width and height of each individual cell in the grid.

If you leave the width or height fields blank then that field will not be changed.

The units that the width and height are measured in are set by the Windows Control Panel. When you enter your measurement in, you can follow it the name of the units that the measurement is in to overrule the Control Panel setting.

cms - Centimeters

mms - Millimeters

inches - inches

pts - Points


A sample of the grid style and spacing is displayed here.


Object Attributes Dialog
Object Attributes

Introduction

The object attributes set the Name, Tags and display style for an object. This dialogue only appears in Edit Mode and the display style section applies only to Use Mode.

The Name is displayed on the object frame and is intended to help the user of the sheet, the Style Tag Name(s) are to allow objects to be selected that are to have the same style, then restyle them as a group. The style tag system is covered in detail in Tags.

The 'Use'Mode Options, sets the display style when the sheet is switched to Use Mode.

Click on the part of the dialogue you need help on.

Objects Affected

All objects are affected.


Object Hidden - hides the object, preventing it from being seen and from being edited when the sheet is in Use Mode.


Frame Hidden - hides the object frame when in user mode. The frame has limited use when in Use mode, so hiding it is not a problem.


Object Locked - Stops mouse and keyboard events to the object, this stops it being edited or changed by the user of the sheet.

It does not stop any changes due to recalculation of the sheet.


Hide Pipes - hides the input and output pipes that feed data into and out of the object. The pipes cannot be moved or re-linked in Use Mode, but they are useful for showing circular references and highlighting errors, so you may not wish to hide them.


Style Tag Names, Enter Tag Names into this section. Each Tag Name is a single word chosen by you, which can be used to locate the object on the sheet. You can enter several of them separated by spaces.


Name of Object, Enter the name of the object. The name can be used to locate the object, but its main use is to help the user of the sheet. You decide the name.

To display the name select:

 Above - to display the name above the frame.

 Below - to display the name below the frame.

 Not Displayed  - to hide the name.

If the name is not displayed, then you could use it to store comments or information about the object.


Tumbler Options Dialog
Tumbler Options

Introduction

The Tumbler object has a text display the shows the value it is sending into the sheet, it also has ticks that mark off the angles. This dialogue sets the options for those two settings.

Text Display

The text display is a box that shows the result of the Tumbler Equation. This is the value that is being input into the sheet.

Off	The display is hidden

Shown Above	The text box is shown above the cylinder of the tumbler

Shown Below	The text box is shown below the cylinder of the tumbler

Graticules

Graticules are ticks that mark off the angles around the tumbler. Major ticks are long lines, minor ticks are the short lines between the longer ones.

To switch on the major or minor ticks, select the appropriate button and set the angle in degrees that the graticule marks off.

Objects Affected

Tumbler


Output Table Settings

Introduction

The output table settings dialogue, sets the display style for an Output Table Object. No other object is affected by this dialogue.

Redimensions to Fit Data

The size of the array grid is adjusted to fit the dimensionality of the data.

The row column numbers are adjusted, not the width or height of rows or columns.

For example if the Output Table is currently 2 columns by 3 rows and you feed a table into it that would cause it to be 1x1. Then it will resize to be 1 column by 1 row.

Display Status Line

This option displays a line, giving the data object type currently displayed on the output table. This is one of the 12 basic data object types CleanSheet supports.

Display Using Array Notation

Displays the data using CleanSheets array notation curly brackets{ }. If this is not selected, then the data is expanded into a grid of rows and columns, which is much more natural for 2 dimensional data.

Objects Affected

Output Table


Paste Picture Dialogue
Paste Picture

Introduction

The paste picture dialogue appears when pasting a picture into a graph object. The graph needs to know what the picture will be used for and hence this dialogue appears.

You can only paste into objects in Use Mode, in Edit Mode the Paste command refers to the whole object and will paste objects onto the sheet.

Use as Background

The graph objects support a picture backdrop behind the graph. This option, sends the picture to the background. Once pasted into the background, you can select how to display the picture by selecting the Background style menu option.

Series A Graph to Series H Graph

The graph objects can handle 8 overlaid series on the same graph. Each series represents one set of data and each can be styled differently.

Selecting one of these options associates the picture with one of the series.

The representation varies according to the Series Options chosen, Column and Bar graphs have the picture filling the column and bar. Marker and Line Graphs have the picture used as the marker and Area Graphs, have the picture filling the area.

To Use a Picture in a Graph

Go to your graphics package, prepare the picture and copy it to the clipboard.

Select CleanSheet

Switch to Use Mode if you are not already in this mode

Click on the frame of the object to select it

Select Paste from the Edit Menu

Select the destination for the graphic within the graph

Objects Affected

Line/Column/Area Graph

Line/Bar/Area Chart


Series Options Dialog
Series Options

Introduction

The series options, set the styles for each data series represented on a graph object. Each series can be styled separately using this dialog.

When in Use Mode, if you double click on a series on the graph object, this dialogue will appear showing the settings for that series.

The best approach to this is the step-by-step approach. Each section is listed below, select any part of the section you need help on.

Step 1 - Select the Series to be Restyled

This section deals with the series being edited and the names of the series.

Step 2 - Select the type of Graph for the Series

This sections sets the graph type.

Step 3 - Set the Fill Style for Column or Area Graphs

This section deals with filled areas, the filled area only applies to column and area graphs, line graphs are not filled.

There are 3 fill styles available, Solid Colour, Graduated Colour and Picture Fill, select one of these to obtain help on it.

Step 4 - Set the Line Style

The line style affects all three types of graph. For the area and column/bar graphs, it changes the style of the border around the area.

Step 5 - For Line Graphs, Set the Marker Style

The marker style applies only to line graphs.

Step 6 - Set the General Series Options

Objects Affected

Line/Column/Area Graph

Line/Bar/Area Chart


Selects the series to edit. The series are initially called Series A to Series H, you can edit the names of the series with the edit box below.


Edit the name of the currently select series.


The column graph displays data as rectangular columns, whose height represents their value. In the horizontal version the columns are shown as horizontal bars.


The area graph plots the data points and fills the area underneath.


The Line graph, joins data points with lines and draws markers at the data points.


Solid Colour, fills the area with a single continuous colour. Once this option is selected, click on the Solid Colour... push button to set the colour.


Graduated Colour, fills the area with colours that smoothly vary between two specified colours.

When this mode is chosen, the Graduated Options become enabled, click on one of these below to obtain further help.


Fill with Picture, fills the area with a picture.

The picture should be pasted into the graph object from the clipboard, for more details see the Paste Picture dialogue.


Solid Colour... Click on this to set the colour for solid colour fills.


Left to Right Graduated Fill Example

Top to Bottom Graduated Fill Example

Top Left to Bottom Right Graduated Fill Example


These buttons set the start and end colour for graduated fills.

Notice that a right to left graduated fill is a left to right graduated fill with the start and end colours reversed.


Picture Options

Align Left	Aligns the picture to the left edge

Align Right	Aligns the picture to the right edge

Centre Horizontally	Aligns the picture centrally

Stretch Horizontally	Stretched the picture horizontally to fit the width

Tile Horizontally	Repeats the picture to fill the width

Align Top	Aligns the picture to the top edge

Align Bottom	Aligns the picture to the bottom edge

Centre Vertically	Centres the picture

Stretch Vertically	Stretched the picture to fill the height

Tile Vertically	Repeats the picture to fill the height


The Line Style for the Line Graphs, or border style for Area and column Graphs.

Off - Line Hidden

Dashed

Dotted

Dash Dot

Dash Dot Dot

Solid


Select the colour of the line from the pallette colours.


Sample of the line style


A sample of the fill style, graduated fill or picture options is given here. Note that the picture is always illustrated as an Argyle pattern, regardless of the picture you have pasted in.


The spot colour of the marker, the contrast colour is taken from the line colour.


The style of marker for line graphs, select from the drop down list.

If Use Picture as Marker is selected, then this is disabled.


Selects the pasted picture as the marker for line-graphs. The picture will be draw centrally over the data point it represents.

To use a picture as a marker, you must first paste in the picture. See the Paste Picture dialogue.


Stack onto Similar Objects - Stacks columns graphs onto column graphs, line graphs onto line graphs and area graphs onto area graphs.

This style is used to create stacked graphs, notice the stacking order below.

Note that you do not need to use this option for Percentage graphs, these are done by setting the scaling to Percentage (See Graph Scale).


Draw Column Series Lines - These are lines draw to join up a single series of columns.

The diagram below illustrates Column Series lines for Series B of a stacked graph.

This option only applies to column graphs. Note also, that to see the lines, there must be gaps between the columns. (See General Options)


Axis and Grid Dialog
Axis and Grid

Introduction

The axis and grid dialogue sets the style of both x & y axes and enables or disables the lines of the background grid. The line style for the grid is set on the Grid Style dialogue.

Click on any part of the dialogue you want help on.

Objects Affected

Line/Bar/Area Chart

Line/Column/Area Graph

XY Scatter Graph

XY Scatter Input

XY Scatter Calculation


The ticks are small lines that cross the axis. Major ticks occur at numbers, minor ticks occur between the numbers.


The ticks are small lines that cross the axis. Minor ticks occur between the intervals. On a logarithmic scale they are spaced logarithmically.


The text on the axis can either appear vertically (reading bottom to top), or horizontally.


Show Axis, displays or hides the line along the axis. The ticks and numbers are still displayed, even if the line isn't.


If Grid Line Ontop is selected, the grid pattern will appear onto of the series columns and graphs.


The Grid lines are the lines covering the graph area. The Major grid lines join to the axis numbers, the minor grid lines occur between the major ones.

To set the line style of the grid, see the Grid Style dialogue.


The Font button sets the font style for the Axis text on both axes.


A sample of the current settings.


Graph Background Dialog
Graph Background

Introduction

This dialogue sets the background style for graph objects. In Use Mode you can quickly get to this dialogue by double clicking on the background of the graph (outside the plot area).

To learn about background styles, click on one of the three styles available, Solid Colour, Graduated Colour or Picture Fill.

Objects Affected

Line/Bar/Area Chart

Line/Column/Area Graph

Output Density Graph

Input Density Graph

Pie Chart

Segment Chart

Polar Graph

Polar Input Graph

Polar Calculation Graph

XY Scatter Graph

XY Scatter Input

XY Scatter Calculation

3D Graph


Graph Scale Dialog
Graph Scale

Introduction

The graph scale dialogue, sets the scaling mode for graphs, or more specifically, it sets the number of intervals, the size of intervals and the special modes of scaling such as logarithmic scaling.

Click on any part you need help on.

Notes on Scaling

Percentage - 	Creates a percentage graph.

Logarithmic - 	Create a Logarithmically scaled graph (used when the data being displayed increases exponentially).

These are normally the only two options on this dialogue you need to select, if you do not need to switch into manual mode scaling, then don't.

That said, there are two separate things involved in scaling, each of which can be switched separately to manual control.

The Scaling determines the step size of each interval.

The Number of intervals determines how many steps there are.

For example, the graph might be scaled with 5 positive steps and 5 negative steps of 10 units, to give a range of -50 to +50.

Objects Affected

Line/Column/Area Graph

Line/Bar/Area Chart


A percentage graph is one where the series are added up for each interval, then each series is displayed as a percentage of the total.


Selecting automatic scaling allows CleanSheet to choose the size of each step.


Manual Scaling, means that you set the Step value and Origin for a graph.

 The Step Value - the size of the step made for each interval on the graph.

 The Origin, if the origin of this axis isn't zero (i.e. it doesn't cross the x axis at 0) then enter its value here.


Logarithmic scaling, creates a graph where the values displayed are spaced logarithmically, e.g., 10,100,1000,10000.

Notice that the step value used to multiply each step, where on a normal graph it is added at each step. Before displaying a value, the  Log of the value is taken (always log to the base 10).

Log graphs always have origins greater than 0, since log (0) gives an error, and the log of negative numbers gives an error. Hence you can never display negative numbers on a Logarithmically scaled graph.

Log graphs are used to display quantities that increase exponentially.

When displaying a log graph the step values will always be a power of 10, because it makes the graph scale easier to read.


Floating Origin. With the scaling set to automatic, CleanSheet will normally keep the origin at 0, since this is less confusing. However, if you want to allow the origin to be varied, then select Floating Origin. CleanSheet will then obtain the maximum spread of values by sacrificing the zero origin.


Automatic intervals, allows CleanSheet to choose the number of intervals to scale the data. For example, if you choose a Step Value of 20, and the maximum value to display is 50, CleanSheet could choose 3 positive intervals to display this.


If 'Manual Intervals' is selected, you can decide how many positive and negative intervals will be displayed on the graph. This restricts CleanSheets freedom and should only be selected if really needed.


This advice box, tells you the limits that the settings will allow. Refer to it after you have made a change to ensure the settings are correct.


General Options Dialog
General Options

Introduction

This dialog sets the options for column, area, bar and line graphs that are not set on other dialogues. It is concerned with global settings for the object, rather than settings for individual series on the graph (See Series Options for this).

The best approach to this dialogue is a step-by-step one.

Step 1 - Edit the Names of the Intervals

This section deals with the interval names.

Step 2 - For column graphs, set the spacing and overlap of the columns.

This section is only relevant to Column and Bar graphs.

Step 3 - Set the General Settings

Step 4 - Set the Style of the Title Box

The title box contains the title of the graph.

Step 5 - Set the Style of the Index Box

The index box contains a key to the styles for each series.

Objects Affected

Line/Column/Area Graph

Line/Bar/Area Chart


The intervals and their current names are listed in this box. Select the name of the interval to be edited.


Edit the name of the interval in this edit field.


Get Names from Input.

If this button is not selected, then the names you have edited in this section remain in force when the sheet is recalculated.

However, if you selected this button, then the interval names will be taken from the input data pipes.

 Interval Names Input.

When the Interval Names input is connected then 'Get Names from Input' will get the names from that input pipe.

 Full Input point.

When the data comes in through the full Input point (top left corner of the frame) then CleanSheet will examine it for interval names. If one column or row of the data obviously represents interval names, then 'Get Names from Input' will extract those names and use them.


% Overlap - the amount that different series of column graphs overlap. 100% means they complete overlap, 0% means they are completely separate.


%Spacing - the amount of space between columns, in terms of the total width of the interval. Obviously 100% spacing would leave no room for the columns and is not allowed. 0% Spacing means the colums touch or overlap.


A sample of the column spacing is shown here.


Interval Names

In the example below the interval names are 'Jan' 'Feb' and 'March'.

Do not confuse the interval names with the series names (in this example 'Series Name A' and 'Series Name B'). Series names are set on the Series Options dialogue.


Show Drop Shadow - a drop shadow is drawn behind the series.

 As you can see drop shadows look effective, but they can also confuse and obscure the data. Use this feature sparingly.


Min - Max lines are vertical lines joining the minimum series for an interval to the maximum. These are normally part of hi-lo graphs.

To Create a Hi-Lo graph, you must have 2 data series.

 Set the graph style on both series to Line Graph. See Series Options.

 Set the Marker style to a horizontal line.

 Set the Line Style to Off.

 On this dialogue, switch on Draw Min-Max Lines.


When CleanSheet scales these graphs it can resize the graph object to suit the new scaling. If you do not want this, select Fix Graph Height. CleanSheet will then adjust the size of the intervals to keep the overall size of the object approximately the same.


Show Title, enables the Text of the title to be displayed. In the default colour scheme, the title is in white and cannot be seen if it is shown against a white background.


Show Title Box - enables the Box enclosing the title to be displayed. The box can be used to make the title stand out.


Font - sets the font style, colour, typeface and size for the title.


Box Colour - sets the colour of the box containing the title.


Edit the title of the graph in this edit field.

Note that when CleanSheet detects what it thinks is a title in the input data, it will overwrite the title you enter here.


A sample of the resulting title is shown here.

Note that if you cannot see the title, and it is switched on, then either there is no text entered or the colour scheme is invisible (e.g. white-on-white).


Show Index Box - switches on display of the index box. Without this option the index box is hidden.


Border Colour - sets the colour for the frame around the index box.


Box Colour - sets the colour of the rectangle behind the index text.


Font - sets the font style for the index box text.


A sample of the index box style is displayed here.


Select Special Dialog
Select Special

Introduction

The tags system within CleanSheet allows you to quickly select several objects and then restyle them as a group. This dialogue allows you to quickly select a group of objects based on their properties.

The properties of Tag Name, Object Name, Object Type and Layer all work together using an AND system, i.e., If Tag Name is X AND Object Name is Y AND Object Type is Z.... then select the object.

If the Object Name or Tag Name is left blank, then it is ignored.

Selecting All Objects

To Select all objects, Leave the Tag Name and Object Name Blank. The Object Type should be set at All Objects. The scope of search should be set to either All Layers or Current Layer depending on whether you want all objects, or just the objects on the current layer.
Click on OK. All the objects will now be selected.

Selecting Named Object

Enter the name of the object in the Object Name field. Leave the Tag name blank. Object Type should be set to All Objects.
Click on OK and any object matching that name (case is ignored) will be selected.

Selecting Tagged Objects

Enter one or more tag words into the Tag Name(s) section. Tag words are counted separately. Any object that contains a tag word that matches any tag word in this list will be selected. Object Name should be left blank, Object Type should be set to All Objects.
Click on OK and the tagged objects will be selected.

Selecting Objects by Type

Leave the Tag Names and Object Names blank, Select the type of object in Object Type and click on OK. All the objects of that type will be selected.

Click on any part of the dialog that you need help on.

This dialogue is only available in Edit Mode, in Use Mode only one object can be selected anyway, so this dialogue is not necessary.


Scope of Search - specifies whether all the layers (all 100) on the sheet will be considered, or just the layer displayed in the top window. Notice that you can have several windows open to the same sheet, each displaying a different layer. The Current Layer is the layer displayed in the top one of these windows.


Deselect Previous Selection - when this is chosen any previously selected object will be deselected, this is the default and is what you'd expect.

However, when this is not chosen, previously selected object remain selected, allowing multiple calls to this dialogue to select multiple groups of objects.

For example, to select all objects named 'My Inputs' and all objects named "My Outputs". Use Select Special to find "My Inputs", then do another Select Special to find "My Outputs", but this time, ensure the "Deselect Previous Selection" button isn't checked.


Tag Name(s) - The tag words used within the object.

Tag words are defined in the objects using the Object Attributes Dialog. Tag words are simply words used to locate the object, they can be any word or words separated by spaces.

Tag Names are checked such that if any object word matches any search word then a match is found.

For Example, if the Object has a Tag Name of "Main Data Circular" and the search Tag is "Circular Processing" this would be a match because "Circular" appears in both word lists.

Case is ignored when comparing words.


Object Name - the name of the object. This is compared with the name defined for each object and if a match is found (ignoring case), then the object passes this test.

The object name is defined on the Object Attributes Dialogue.


The Object Type is used to restrict the search to particular types of CleanSheet objects. For example Input Tables and Tumblers are 2 different types of CleanSheet object.

The first option in this list is always "All Objects", when this is selected, Object Type is ignored.


Save Options Dialog
Save Options

Introduction

Save options appears from the options button on the main Save As... dialogue. It supports 2 options, backup files and password protection.

Backup File

When a document is saved, any older version of the document is renamed so that it ends with a CBK extension. This keeps a backup copy, one generation behind the current file, on the disk.

Protect with Password

Enter a password in the password section. When this document is Opened, CleanSheet will prompt you for a password. You cannot open a password protected file without the password.

This cannot be emphasized too much - if you forget the password, you have lost the data. We will not under any circumstance break the password for you.


Title

Introduction

Objects Affected


Title

Introduction

Objects Affected


Print Dialog
Print

Introduction

When you select Print, this dialogue asks you specifically what to print and how to print it.

Click on any part you need further help on.

A step-by-step approach to printing a sheet.

Step 1 - Print Range

The print range is the selection of layers on the sheet to print. The layer range is inclusive, i.e., layer 1 to layer 3 specifies layers 1,2 and 3.

Regardless of the layers you choose, CleanSheet will not print layers that do not contain any objects, so its safe to include layers you think may be empty.

Print Layers Separately - With this option, each layer is printed, starting from the lowest through to the highest, starting a new page after each layer.

Without this option, the layers are collapsed into a single print with the object overlaying each other.

Step 2 - General Settings

Set how many copies to print, and if the copies are to be collated, select Collate. Collate changes the order of the copies so that all the pages for copy 1 are together, then all the copies for copy 2 are together.

Select Print to File if the data is to be redirected to a file. Note - print to file is nothing to do with the Printer Manager spooling facilities.

Percentage Scale - scales the sheet before printing. Scaling the sheet to 50% will allow you to fit 4 times as much on each page (twice as much vertically and twice as much horizontally).

Step 3 - The Page Breaks

CleanSheet intelligently places page breaks in an attempt to minimise the number of objects it has to slice through. You may however, prefer to do this manually.

See Page Breaks

Step 4 - The Page Layout

The page layout specifies the margins, header and footer for the page. See Page Layout for details.

Step 5 - What to Print

You normally don't want to print the detail behind the sheet, since its of minimal use. The usual printout is just the inputs and outputs objects - The inputs into the sheet you made, and the output results you obtained.

It is therefore normally fine to leave this section at its default.

Step 6 - Print

Ensure there is paper in the printer and click on OK.

If you have enabled the Print Manager, then the printout will not begin immediately. Instead the print data will be spooled to disk and when that is complete, then the Print Manager will send the data out to the printer, freeing the computer to continue work.


All Layers - instructs CleanSheet to print all of the layers on the sheet.

Note that regardless of this, CleanSheet will not print any empty layers.


Layers - Enter the range of sheet layers to print. The range you enter is treated as an inclusive range, e.g., range 3 to 5 specifies layers 3, 4 and 5.

Notice that regardless of the range specified, CleanSheet will not print layers that do not contain anything.


Print Layers Separately.

When this is selected the layers are printed on separate sheets of paper, starting from the lowest to the highest.

When this isn't selected the layers are overlaid and printed in one go.


Copies - The number of copies of the printout to print.


Collate - If selected, the order of the printout is collated so that copy 1 is printed first, then copy 2, and so on.

If this option is not selected, then several copies of the first sheet will be printed first, then several copies of the second sheet and so on.


Print to File - If Print To File is chosen, then CleanSheet will prompt you to specify a file to print to. The printout will then be re-directed to that file.

Notice that this is nothing to do with the Printer Managers print spooling facility.


Percentage Scale - The amount to scale the sheet by before printing. The scale is specified as a percentage, a smaller number means the sheet is printed smaller and hence more of the sheet fits onto each sheet of paper.


What to Print - determines which objects and parts of objects to print.

Object Frames, if this is selected, the frames around objects are printed.

Data Pipes, if selected the connecting pipes to the objects are printed. If a pipe spans multiple layers, it will be printed on the lowest layer it connects to.

Input Objects - objects used to input data onto the sheet, such as the Input Table, Tumblers Objects etc.

Output Objects - objects used to display data, such as the Output Table, Pie Chart etc.

Calculation Objects - any object that is not an input or output object.


Page Breaks Dialog
Page Breaks

Introduction

With a sheet that is larger than a single sheet of paper, CleanSheet must break the sheet up into pages. It tries very hard to place the page breaks between objects, but it doesn't always succeed.

The page breaks dialogue allows you to place hard page breaks on the sheet and thereby specify where the pages will start.

When placing page breaks work from top left to bottom right, when you place a hard page break, CleanSheet will re-adjust the soft page breaks to take advantage of the new pagination.

Placing a Hard Page Break

The outlines of the objects are shown as rectangles, the soft CleanSheet page breaks are shown as dotted lines, any hard (user set) page breaks are shown as solid lines.

To place a hard page break, click the mouse where the page break will be. A vertical page break line will be placed.

You cannot place horizontal page breaks this way because it is not necessary. The more usual way to use this dialogue is to move soft page break. If there are no soft page breaks to move, then the objects fit on a single sheet and there is no point in placing a page break.

Moving an Existing Page Break

Place the mouse over the line representing either a soft or hard page break. The mouse cursor will change style. Click and drag the page break to its new position.

Removing a Page Break

You can only remove hard (user defined) page breaks.

Move the mouse over the page break and drag it completely off the window. It will be deleted.

Layer

If you have opted to print layers separately, then the page breaks must be set for each layer. The layer selection list, allows you to select the layer whose page breaks you wish to edit.

If you are printing all layers together, than there is only one set of page breaks to edit and hence this option is disabled.

Clear All

Clears all of the hard page breaks shown on the display. If you have selected Print Layers Separately, then only one layer is displayed and only one layer's page breaks will be cleared.


Page Layout Dialog
Page Layout

Introduction

The page layout dialogue sets the margins, header and footer during a Print run.

Click on any part you need help on.

To Edit the Margins Graphically

Drag the margins in the sample window on the left, the new values will be updated in the Margins section.

To Add a Header

Enter the text of the header in edit field 1,2 or 3 (which corresponds to Left Top, Centre Top, and Right Top on the page). Text entered will be printed on the page heading, left aligned, centred and right aligned accordingly.

To Add a Footer

Enter the text of the footer in edit fields 4,5 or 6 (which correspond to Left Bottom, Centre Bottom and Right Bottom on the page). Text entered will be printed at the foot of the page.


This section shows a sample of the paper, with the page shown as a rectangle. The numbers 1,2..6 correspond to the header and footer sections 1 to 6. Text entered in these fields will be printed at the corresponding place on the page.

You can edit the margins in this section by dragging them with the mouse.


The margins specify the gap between the edge of the paper and the edge of the printed area of the page. These margins are displayed in centimeters or inches depending on the settings within Windows Control Panel. To enter values in other units, type cms  (for Centimeters), inches, mms (for millimeters) or pts (for points) after the number. For example 2cms is always a margin 2 centimeters wide, regardless of the units CleanSheet displays lengths in.

Check you margins in the sample window to see they look reasonable.


Font - the font button selects the style of the header and footer text.


These 6 edit fields correspond to the six parts of the header and footers. See the sample window for the position that each part will be printed.

As well as literal text, you can enter codes that begin with Ampersand (&) for items such as Page Number and Layer. These codes will be substituted by the appropriate number during the print.

To enter a special code, select it from the list at the bottom.

Example: The string "Tile (&X,&Y)" would appear as "Tile (0,0)" on the first page.


This list contains the codes that can be placed within CleanSheets headers or footers.

Example: To enter the page number into the centre of the header, place the edit cursor inside edit field 2 and then select the "Page Number" from the list, a "&P" will be inserted into the text - this is the code for the page number.

The Codes are:

Page Number 	The page being printed

Layer 	The sheet layer begin printed

Today's Date (Short) 	The system date, e.g., 20th Jun 93

Today's Date (Full) 	The system date e.g., June 20th 1993

Time 	The system time, e.g. 18:46

Sheet Name 	The filename of the sheet.

Tile X 	The X position of the tile (runs 0,1,2...)

Tile Y 	The Y position of the tile (runs 0,1,2...)

The sheet is broken into tiles, small enough to fit onto a page. The Tile position shows how each page fits into the whole sheet.


Density Map Style Dialog
Density Map Style

Introduction

A density chart, displays values by varying the size and colour of dots, or squares on a grid. The Density Map Style dialogue, defines exactly how to vary the colour and size of those marks.

This dialogue essentially consists of 2 settings - the Size Variation and the Colour variation, as long as you remember this you should not find this dialogue daunting.

The best approach to this dialogue is a step-by-step approach.

Step 1 - The type of marker used - Marker Type.

The Rectangle style marker - can vary in size and colour - it's simply a filled rectangle.

The Circle/Ellipse style marker - an ellipse marker can vary in size and colour.

The Picture marker - this marker cannot vary in colour, only in size. The exact look of it, depends on the picture you paste into the Density graph from the clipboard.

Step 2 - How to Vary Size

Vary Length	This varies the width and height in proportion to the value it represent. This may give a false representation if used carelessly. A marker twice as wide and twice as high may appear to the eye to be 4 times as large.

Vary Area	This varies the width and height in proportion to the square root of the value it represents. In essence the Area is proportional to the value of the marker.

Vary Volume	This varies the width and height in proportion to the cube root of the value. In essence the Volume is proportional to the value of the marker. This is useful in examples like the House marker shown above. It appears to be 3 dimensional and should grow as though it was 3 dimensional.

Step 3 - How to Vary

This section and the ones below it specify how the value is convert to a size and colour. Select the option below to obtain help on it.

Vary smoothly between two fixed limits, you specify a lower and upper value and the colour and size each represents. CleanSheet then smoothly varies the marker between these two limits.

Vary smoothly between minimum and maximum values, you specify the style of the lower and upper limits, but the values that these represent are taken as the minimum and maximum values in the input data. This ensures that the minimum value always has the style of the lower limit and the maximum value always has the style of the upper limit.

Vary smoothly between zero and maximum value, the lower limit style is associated with the value zero and the upper limit style is associated with the maximum value in the input data.

Vary in discreet intervals, the user specifies intervals, any value within that interval is given the specified style.

Density maps cannot display negative values.

Objects Affected

Output Density Graph

Input Density Graph


Smooth Variation between two fixed limits.

This option varies the size and colour of the marker between two fixed limits. The next step is to set the two fixed limits.

This section of the dialogue deals with the fixed limits, read the lines horizontally.

Lower Value 0, matches colour blue and % size 0.

Upper Value 100, matches colour orange and % size 90.

Hence a value of 50, would have a marker whose size is 45% and colour orange-blue.

The size is taken against the size of one grid square. Either the length of the sides, area of the square or volume of an cube based on the grid square according to your selection from the How to Vary Size options.


The Lower Value that corresponds to the lower colour and lower %size.

Notice that any value below this lower limit, is drawn in the same lower value style.


The colour that will be matched to the lower limit. To change it click on the rectangle of colour.

To keep the colour constant, set the lower and upper limit colours to be the same.


The %Size that the lower limit value corresponds to. This is based on the size of the grid. 100% always corresponds to whole grid cell. Either 100% of the length of its sides, 100% of its area, or 100% of its apparent volume, depending on you choice of length, area or volume.


The Upper Value that corresponds to the upper colour and %size.

Any values greater than this upper limit are drawn in the style of the upper limit.


The colour that corresponds to the upper limit. To change it, click on the rectangle of colour.

To keep the colour constant, set the lower and upper limit colours to be the same.


The %Size that the upper limit value corresponds to. This is based on the size of the grid. 100% always corresponds to whole grid cell. Either 100% of the length of its sides, 100% of its area, or 100% of its apparent volume, depending on you choice of length, area or volume.


Smooth variation between Minimum and Maximum

This option varies the size and colour of the marker so that the lower limit style corresponds to the minimum value in the input data and the upper limit style corresponds to the maximum value in the input data. The next step is to set the upper and lower styles.

This section of the dialogue deals with the styles, read the lines horizontally.

Lower Value <Minimum>, matches colour blue and % size 0.

Upper Value <Maximum>, matches colour orange and % size 90.

The minimum and maximum values will be recalculated on the next recalculation of the sheet.

The size is taken against the size of one grid square. Either the length of the sides, area of the square or volume of an cube based on the grid square according to your selection from the How to Vary Size options.


The Lower limit is not used in this mode, instead the minimum value from the data being displayed is used.


The Upper limit is not used in this mode, instead the maximum value from the data being displayed is used.


Smooth variation between Zero and Maximum

This option varies the size and colour of the marker so that the lower limit style corresponds to zero and the upper limit style corresponds to the maximum value in the input data. The next step is to set the upper and lower styles.

This section of the dialogue deals with the styles, read the lines horizontally.

Lower Value <Always 0>, matches colour blue and % size 0.

Upper Value <Maximum>, matches colour orange and % size 90.

The minimum and maximum values will be recalculated on the next recalculation of the sheet.

The size is taken against the size of one grid square. Either the length of the sides, area of the square or volume of an cube based on the grid square according to your selection from the How to Vary Size options.


The Lower limit is not used in this mode, instead the value 0 is always taken as the lower value.


Vary in Discreet Intervals

In this mode the variation occurs in discreet steps. The table of steps is entered in the bottom section of the dialogue.

The table represents particular point values, for example, in the above table, the following would result.

Values between 0 and 50 would have 0 % size and hence not be drawn.

Values greater than or equal to 50, but less than 100 would be drawn in green at 50% size.

Values greater than or equal to 100, would be draw at 90% size in blue.

The size is taken against the size of one grid square. Either the length of the sides, area of the square or volume of an cube based on the grid square according to your selection from the How to Vary Size options.

Further help is available on adding, deleting or changing entries in the table.


Values are entered here prior to adding to the list. If the value is not added to the list, it has not effect.


Set a colour here by clicking on the rectangle of colour.


The % size is set here, this is a %size based on each cell within the grid used to display the results.


The list of intervals is shown here. This list contains the discreet intervals for the graph.


To add an interval to the list

Enter its value, this will represent the lower limit of the interval

Click on the colour rectangle and select the colour

Enter the % size

Click on Add.

The interval will be entered in the correct place in the list.


To Delete an Interval from the List

Click on its entry in the list

Click on Delete.


To Change a Value in the List

Click on its entry in the list

Change the lower value, colour and size

Click on Change

It may be moved in the list to keep the Values in ascending order.


Index Box Dialog
Index Box

Introduction

The index box is a box containing the key to a graph. On some graphs the index box shows which series match which graphs (XY Scatter Graphs do this), on other graphs it shows how the values are displayed (Density Graphs do this for example).

This dialog, determines the style of that box.

Click on any item you need help on.

Objects Affected

Output Density Graph

Input Density Graph

Pie Chart

Segment Chart

Polar Graph

XY Scatter Graph

3D Graph


Title Box Dialog
Title Box

Introduction

This dialogue sets the style of the title from graph objects.

Click on any part you need help on.

Objects Affected

Output Density Graph

Input Density Graph

Pie Chart

Segment Chart

Polar Graph

Polar Input Graph

Polar Calculation Graph

XY Scatter Graph

XY Scatter Input

XY Scatter Calculation

3D Graph


Title

Introduction

Objects Affected


Paste Picture Dialog (Density Graphs)
Paste Picture

Introduction

The paste picture dialogue appears when pasting a picture into a density graph. There are two uses for pictures on a density graph. It can either be used as the background (this is usually a map for this object type), or it can be used as a marker. The Paste Picture dialogue ask you which it is to be.

You can only paste into objects in Use Mode, in Edit Mode the Paste command refers to the objects and will paste objects onto the sheet.

Use as Background

The density map objects support a picture backdrop behind the graph. This option, sends the picture to the background. Once pasted into the background, you can select how to display the picture by selecting the Background style menu option.

Use as Marker

This selects the picture for use as a marker. Having pasted the picture in, you should set the correct style on the Density Map Style dialogue.

To Use a Picture in a Density Map

Go to your graphics package, prepare the picture and copy it to the clipboard.

Select CleanSheet

Switch to Use Mode if you are not already in this mode

Click on the frame of the object to select it

Select Paste from the Edit Menu

Select the destination for the graphic within the graph

Objects Affected

Output Density Graph

Input Density Graph


Density Paint Mode Dialog
Density Paint Mode

Introduction

The density paint dialogue is only used with the Density Input Object. It tells the object what action to take when the user clicks within the object's rectangle.

This is only relevant when in Use Mode, in Edit Mode, clicking on an object moves or selects the whole object.

Move and Resize Components. For most graphs when you click on any part, that part is selected for resizing. When this button is selected, clicking on a Density Input object has exactly that effect. The normal resizing and editing of components is enabled. Painting of data is disabled.

Paint the Data. When this is selected, mouse clicks on the Density Graph will paint data onto it.

Density Value to Paint With

When painting data, the value to paint is entered here. The marker on the right will display what the data looks like when painted.

Objects Affected

Input Density Graph


Paste Picture - Pie and Segment Charts
Paste Picture

Introduction

This paste picture dialogue appears when a picture is pasted into a Pie Chart or Segment Chart. The first option Use as Background, drops the picture in behind the chart as a backdrop. The style of this picture can then be changed using the Background Style dialogue. The remaining 3 options are specific to Pie and Segment charts, these options are illustrated below.

You can only paste into objects in Use Mode, in Edit Mode the Paste command refers to the objects and will paste objects onto the sheet.

Setting the Shape

If you paste a picture into crust of a pie or segment chart, you must let CleanSheet know what shape it is. This is done using the Pie Chart Style or Segment Chart Style dialogues. If you do not specify the shape, CleanSheet will assume the picture is rectangular.

To Use a Picture in a Pie/Segment Chart

Go to your graphics package, prepare the picture and copy it to the clipboard.

Select CleanSheet

Switch to Use Mode if you are not already in this mode

Click on the frame of the object to select it

Select Paste from the Edit Menu

Select the destination for the graphic within the graph

If the picture is to be used in the crust, set the shape within the Pie Chart Style or Segment Chart Style dialogue.

Objects Affected

Pie Chart

Segment Chart


Pie Chart View

Introduction

This dialogue, sets the angle of view and depth for Pie Charts.

Depth of Pie Chart

The height of the pie chart scaled as a percentage of the horizontal radius. Since this object covers both 2 and 3 dimensional pie charts, to produce a 2D Chart this must be set to 0.

Angle of First Slice

The Angle in degrees that the leading edge of the first slice will be taken at. The angles are measured anti-clockwise.

Elevation Angle

An elevation angle of 0 is taken as a view directly down onto the chart, and angle of 80 is a much lower down view.

To create a 2 dimensional Pie Chart, this must be set to 0.

Examples

Objects Affected

Pie Chart


Shape of Picture Dialog
Shape of Picture

Introduction

When a picture is pasted into a Segment Chart or Pie Chart, there is not enough information in the picture for CleanSheet to decide what shape it should be. Without this information, CleanSheet assumes the picture has a rectangular shape.

This dialogue sets the shape of a picture, it is selected via the Shape button on the Pie Chart Style or Segment Chart Style dialogues.

To Traces the Shape

Click the mouse button at some point on the edge of the shape. Click again further round the edge and keep clicking at points around the edge until the shape is defined using many small line segments.

You should use the minimum number of line segments possible to trace a shape.

You can end the tracing of shapes at any time by double clicking the mouse cursor.

To Edit the Shape of the Trace

Move the mouse over the point to be moved. The cursor will change shape. Drag the point to its new position.

To Return to the Default Rectangle

Click on the Default button to return to the default bounding rectangle.

The Effect of Shape on a Chart

When CleanSheet knowns the shape, it can use it to place the edges when viewing in 3 dimensions.

Objects Affected

Pie Chart

Segment Chart


Pie Chart Style Dialog
Pie Chart Style

Introduction

The pie chart style, sets the colour of the segment faces on a Pie Chart, and the segment text legend style.

You can quickly get to the styles for a particular segment by double clicking on that segment when in Use Mode.

The Crust, Filling and Edge

The Crust Style

Click on any part you need help on.

The Filling Style

The Edge Style

The Line Style

This section of the dialogue allows you to place lines around the edges of segments.

Legend Style

This section deals with the text legends that provide a key to each segment.

Objects Affected

Pie Chart


Crust is Picture. If this is selected, then the crust is a picture, rather than a solid shape. To use a picture as the crust see Paste Picture.


Crust is Solid Colour. The crust is drawn as a normal solid pie slice when this button is selected.


Before changing the colour of a segment, you should select which segment is to change. A list of segments is presenting in this box.


This button is used to define the shape of the crust. It is only used when the crust has a picture pasted into it. For more details on the effects of shape on a pie chart, see the Shape Dialogue.


This button changes the colour of the crust for the chosen segment.


Filling is picture - to use this option, a picture must have been pasted in from the clipboard for use as the filling. This switches on the picture.


Filling is Solid  Colour - this is the normal style for the pie segments, the filling is drawn in a solid colour specified by you.


Each segment can have a different colour for its filling. You must select a segment whose filling colour is to be changed.


The colour button changes the colour of the filling. Before using this button, select which segment the change of colour will apply to.


Edge is picture - to use this option, a picture must have been pasted in from the clipboard for use as the edge. This switches on the picture.


Edge is Solid  Colour - this is the normal style for the pie segments, the edge is drawn in a solid colour specified by you.


Each segment can have a different colour for its edge. You must select a segment whose edge colour is to be changed.


The colour button changes the colour of the edge. Before using this button, select which segment the change of colour will apply to.


Each segment has its own line style. Select which segment's line style is to be changed.


Surround with Line - when this is selected, the faces are edged with a line.


Select the colour of the line in this colour section.


The type of text Legend.

None	No text legend

Segments % Size 	example 30%, 60%, 10%.

Segments Name 	The name of the segment (which is obtained from the data coming in through the input pipe).


Horizontal	The text is draw horizontally

Radial	The text is draw radiating from the centre


Inside	The text is inside the pie segments

Outside	The text is outside the pie segments


Font - sets the font used for the text legend.


A representation of the options chosen is shown here.


Segment Chart Style Dialog
Segment Chart Style

Introduction

The segment chart style, sets the colour of the faces on a segment chart and the style of the text legend.

You can quickly get to the styles for a particular segment by double clicking on that segment when in Use Mode.

The Crust, Filling and Edge

The Crust Style

Click on any part you need help on.

The Filling Style

The Edge Style

The Line Style

This section of the dialogue allows you to place lines around the edges of segments.

Legend Style

This section deals with the text legends that provide a key to each segment.

Objects Affected

Segment Chart


Crust is Picture. If this is selected, then the crust is a picture, rather than a solid shape. To use a picture as the crust see Paste Picture.


Crust is Rectangle. The crust is drawn as a normal solid segment rectangle.


Before changing the colour of a segment, you should select which segment is to change. A list of segments is presenting in this box.


This button is used to define the shape of the crust. It is only used when the crust has a picture pasted into it. For more details on the effects of shape on a segment chart, see the Shape Dialogue.


This button changes the colour of the crust for the chosen segment.


Filling is picture - to use this option, a picture must have been pasted in from the clipboard for use as the filling. This switches on the picture.


Filling is Solid  Colour - this is the normal style for the segments, the filling is drawn in a solid colour specified by you.


Each segment can have a different colour for its filling. You must select a segment whose filling colour is to be changed.


The colour button changes the colour of the filling. Before using this button, select which segment the change of colour will apply to.


Edge is picture - to use this option, a picture must have been pasted in from the clipboard for use as the edge. This switches on the picture.


Edge is Solid  Colour - this is the normal style for the pie segments, the edge is drawn in a solid colour specified by you.


Each segment can have a different colour for its edge. You must select a segment whose edge colour is to be changed.


The colour button changes the colour of the edge. Before using this button, select which segment the change of colour will apply to.


Each segment has its own line style. Select which segment's line style is to be changed.


Surround with Line - when this is selected, the faces are edged with a line.


Select the colour of the line in this colour section.


The type of text Legend.

None	No text legend

Segments % Size 	example 30%, 60%, 10%.

Segments Name 	The name of the segment (which is obtained from the data coming in through the input pipe).


Horizontal	The text is drawn horizontally

Axial	The text is drawn axially


Inside	The text is inside the segments

Leading Edge	The text is outside on the leading edge side

Trailing Edge	The text is along the trailing edge

The exact meaning of leading edge and trailing edge depends on the rotation and shape. The best way to work it to try leading edge text and if it appears on the wrong side, try trailing edge text instead.


Font - sets the font used for the text legend.


A representation of the options chosen is shown here.


When the segment's crust is rectangular, rather than a picture, the rotation of the rectangle in degrees is set here. A rotated rectangle looks more 3 dimensional that an non-rotated rectangle.


Segment Chart View Dialog
Segment Chart View

Introduction

This dialogue, sets the angle of view, depth and separation for a Segment Chart.

Segment Axis Angle

The angle in degrees of the line along which the segment chart will be segmented. This is normally along one edge of the object, when it isn't along an edge, this chart gives misleading result. Consider the two examples below, the first axis is along an edge and the second isn't. The arrow indicates the axis angle.

In each case the segments are all the same size. In the second example do they look the same size?

Depth of Segment

The depth or height of the segments as a percentage of the width of the standard rectangle. When you create a 2 dimensional segment chart, this should be set to 0.

% Space between Segments

The spacing between two segments. The space in added along the axis line, the amount of space is based on a percentage of the size of the standard rectangle.

0% means that the segments touch.

Objects Affected

Segment Chart


Title

Introduction

Objects Affected


Title

Introduction

Objects Affected


Polar Scaling Dialog
Polar Scaling

Introduction

The polar scaling dialogue, sets the scale mode and manual settings for Polar Graphs. There is only one thing to scale on a polar graph, the radius.

Notice there is no Logarithmic option on this dialogue. There is no such thing as a Logarithmic Polar graph because a Log graph requires a non-zero origin and a polar graph must have an origin crossing at zero. If you require a log chart that is really an x-y chart with the x axis wrapped in a circle, then take the log of the radii before feeding it into a normal polar graph.

Automatic

When this is selected, scaling is automatic. CleanSheet will adjust the scale to fit the data. This is the normal mode.

Manual

In manual mode, you must specify the number of intervals and the step value (the size of each interval). For example a step value of 50 and 5 intervals, would allow radii up to 250 units in length to be displayed (or -250 units for that matter).

When using a Polar Input object, it is normal to switch scaling to manual and set the scale to cover the range of values you want to input. This stops the scale changing each time you place a point onto the graph.

Objects Affected

Polar Graph

Polar Input Graph

Polar Calculation Graph


Polar Axis and Grid Dialog
Polar Axis and Grid

Introduction

This dialogue sets the style of the axis, grid and sets the Radians or Degrees option for polar graphs.

Taking this dialogue step-by-step is the best approach.

Step 1 - The Radial Axes

Radial axes are the lines that radiate outwards from the centre.

Step 2 - The Horizontal Axis

Click on any part you need help on.

Step 3 - The Vertical Axis

Step 4 - The Grid Circles

The Grid Circles are the concentric circles that mark off the intervals. Click on any part of this section you need help on.

Step 5 - The Axis Font

To change the style, size or typeface of the font used to display the axis text, click on the Font button.

Step 6 - Radian or Degrees

The radians / degrees button determines whether one circle equals 360 degrees, or one circle equals 2 *Pi Radians.

There is more at stake than simply the display of angles. This option decides how CleanSheet interprets the angles it receives in the input data. If the input data contains a coordinate pair {10,5} r is 10 units, but is the angle 5 radians, or 5 degrees? This option specifies which.

Objects Affected

Polar Graph

Polar Input Graph

Polar Calculation Graph


Off - No radial lines

Quarters, Split into 90 degree (PI/2) segments

Eigths, split into 45 degree (PI/4) segments

Twelfths, split into 30 degree (PI/6) segments


Show angles at tips - the angle of each radial axis line is drawn at its outermost tip. 0 is horizontal to the right, angles increase in an anti-clockwise direction.

The angles are either drawn in radians or degrees depending on the settings on this dialogue.


Ticks on Diagonals - the ticks are small dashes that mark the intervals. By default the ticks only appear on the horizontal axis, if you select this option, they also appear on the diagonal axes as well.


Axes draw ontop. Normally the axis lines are drawn first, then the series lines for the graphs. This results in the axis appearing behind the series graphs.

If this button is selected, the axis lines are drawn ontop of the series graphs.


If this option is selected, the text on the left hand size of the horizontal axis is drawn.


If this options is selected, the text on the right hand size of the horizontal axis is drawn.


The text on the horizontal axis can be vertical (perpendicular to the axis), or horizontal (along the axis).


The Ticks, are short lines that mark an interval along the axis. The ticks on the horizontal axis can be above or below the axis. To get ticks crossing the axis, select above and below.


If this option is selected, the vertical axis text in the upper half of the polar graph is drawn.


If this options is selected, the vertical axis text in the lower half of the polar graph is drawn.


The axis text can be drawn vertically (along the axis) or horizontally (perpendicular to the axis).


The ticks are small lines that mark off the intervals. The ticks on the vertical axis can be to the left of the line, the right of the line or to get them crossing the line, select both left and right side ticks.


Major Grid Circles - are circles drawn on each interval (where the axis numbers mark off the intervals). Selecting this option, enables those circles.


Minor Grid Circles - are circles drawn half way between each interval.


Outer Grid Circle - draws the outer circle the encloses the Polar Graph. It is sometimes useful to have this circle, but not the inner circles in a polar graph.


Circles Drawn Ontop - if this is selected, the grid circles will be drawn ontop of the series data, rather than behind.


The colour of the lines the circles are drawn with is set by this colour selector.


The style of the lines, used to draw the grid circles is set by this selector.


Grade with Colour - if this option is selected, then the circles are filled with colour. The colours vary steadily from the outer colour to the inner colour.

Example, if the outer colour is blue and the inner colour red, the circles could look like this.


Polar Series Style

Introduction

This dialogue sets the style of each series on polar graphs. There can be up to 8 series displayed on a single polar graph and each series can have a different style.

This dialogue benefits from a step-by-step approach.

Step 1 - Select which Series to Restyle

You can also edit the name of the series in this section.

Step 2 - Select the Marker Style

The markers highlight the points shown on the polar graph.

Step 3 - Set the Series Line Style

The series line is a line that joins the points of a series together.

Step 4 - Set the Circle Style

The series circles are circles that pass through a plotted point. You can traces around a circle to where it cuts an axis and hence read off the radius.

Step 5 - Set the Line to Origin Style

The line to origin can be used with the arrowhead marker to produce vector arrows from the origin.

Step 6 - Set the Fill Style

When this option is selected, the area enclosed by the series points is filled with the specified colour.

Objects Affected

Polar Graph (Output Graph Only)


Select the series you want to restyle from this selection box.


Edit the name of the selected series in this edit field.


Draw Marker at Point - if this is selected, then a marker is drawn on the plotted point, if you do not select this, then no marker is drawn.


This section sets the colour of the marker. Note the marker is actually 2 colours. This specifies the main marker colour, the other colour is the line colour of the line that joins the series points.


The marker type is set in this selection box. Select which marker to display at each plot point.


When the arrow head style is selected, instead of the marker, an arrow head is drawn. This should be used when there is a line to the origin. The arrow head turns the line into a vector from the origin to the plotted point.


The Line Styles.

Off - Line Hidden

Dashed

Dotted

Dash Dot

Dash Dot Dot

Solid


This selection box sets the colour for the series line.


The colour of the circle is set by this selection box.


This selection box sets the colour of the line joining the series point to the origin.


Select this check box to fill the area enclosed by the series points with colour.


This button sets the colour of the area enclosed by the series points.


Paint Mode (Polar Graph) Dialog
Paint Mode

Introduction

This dialogue determines what happens when mouse actions are performed on the Polar Input and Polar Calculation objects.

Normally graph objects have their components moved or resized using the mouse, but input graph objects also need the data painted onto them. To resolve this, a paint mode dialogue specifies which action to perform.

This dialogue only appears in Use Mode. Mouse actions in edit mode always refer to the whole of the object to move or resize it on the sheet.

Move and Resize the Graph Components

When this is selected, clicking on the parts of the graphs selects then, and dragging the resize handles changes that parts size. This is the normal action for other graph types.

Paint Coordinate Data

With this mode selected, clicking the mouse will place a data point on the graph. You cannot move or resize parts of the graph in this mode.

Objects Affected

Polar Input Graph

Polar Calculation Graph


Polar Function Points Dialog
Polar Function Points

Introduction

A Polar Calculation Graph has a curve that defines the function it is to perform. If the function already exists as a graph, it may be easier to scan the graph into the computer with a scanner, paste it into the background of the polar graph and then trace its curve. If the function exists as a set of data points, then this dialogue should be used to enter and edit the list.

This dialogue adds, changes and deletes points on the polar calculation object. It only appears in Use Mode.

Click on any part you need help on.

To Add a Point to the Curve

Enter the angle of the point. This angle must be in the same units (radians or degrees) that the graph is set to.

Enter the radius, the graph will be rescaled if necessary.

Click on Add.

The new point will be added into the list at the correct place (placed to keep the angles in ascending order).

To Change a Point on the Curve

The points on a curve are referenced by their angles, if you need to change the angle as well as the radius, delete the old point and add a new point.

Click on the point whose value you want to edit. Its radius and angle will appear in the edit edit fields.

Edit the new radius, (you cannot change the angle)

Click on Change.

The specified angle will have its radius changed to the new value.

To Delete a Point from the Curve

Click on the point to be deleted.

Click on delete

Objects Affected

Polar Calculation Graph


Angle - enter the angle of a data point here. The angle must be in the same units (radians or degrees) as the graph.


Radius - the radius of the data point (the length from the origin to the point).


A plot of the functions points is shown in this section.

Positive radius points are shown in blue.

Negative radius points are shown in red.

The point shown by the angle and radius, is highlighed with a cross.

You can select a point for editing by clicking on it.


Add - Adds the Radius and Angle entered in the Radius and Angle fields to the curve.


Change - Changes the point whose whose angle is entered in the Angle field, to have the new radius entered in the Radius field.


Delete - remove the point whose angle is entered in the Angle field.


Clear All - delete all points on the graph.


Sort Object Contents Dialog
Sort Object Contents

Introduction

This dialogue specifies how to sort an objects contents.

Note that this is not the dialogue that controls the operation of the Sort Object, for that dialogue see Sort Type.

The sorted area is the selected area of the Table. If no area is selected, then the whole Table is sorted. If you select a single column for sorting, only that column will be sorted, if you select two columns and sort the first, then the corresponding rows of the 2nd column will be re-arranged aswell.

Consider this dialogue Step-by-Step

Step 1 - Order of Sort

This section governs how objects are compared. Click on any part you need help on.

Step 2 - Sort Key

The sort key defines what part of the table to examine when sorting. If you sort a table into ascending order by reference to column 0, then the rows will be rearrange so that column 0 is in ascending order.

Example

A table of scores for 4 people looks like this:

If only the first column is selected, and sorted into descending order:

Notice that the second column is unaffected.

If no area is selected, or if both columns are selected, then the whole Table is sorted:

The table is sorted by reference to the first column (column 0) into descending order. Hence column 0 is now in descending order. But notice that the second column is not in descending order, it has been rearranged in the same way that the first column was rearranged. The scorings are still correct - Jacks scored 22, after the sort he still scores 22 and so on.

If both columns are selected and column 1 (the second column containing the scores) is sorted into descending order:

The Table now lists the results, highest score first, lowest score last. The names have also been re-arranged to keep the correct name with the matching score for that person.

Objects Affected

Input Table


Ascending - The table is sorted into strict ascending order, the comparison used is the > (greater than) CleanSheet operator. For example string objects would be sorted into ascending alphabetic order.


Descending - The table is sorted into descending order, the comparison used is the < (less than) CleanSheet operator. For example numeric objects would be sorted, largest first, smallest last.


Nearness - This sorts the data so that the nearest match to the comparison object (nearest as defined by the Vague Logic engine in CleanSheet) appears first in the list.

For example the string objects "Jonas","Jones","Jacks","Kacobs" sorted in terms of how near they are to "Jacobs" would result in "Kacobs","Jacks","Jonas","Jones" because "Kacobs" has only 1 letter different.


Farness - The data is sorted so that the worst match appears first in the list. The comparison used is the vague logic engine within CleanSheet. This is the opposite of Nearness.


Comparison Object - This defines the object to compare against for the nearness and farness options. The text entered here must be a CleanSheet data object.

Examples:

12.453	A number

"Kacobs"	A string object - the quotes define the string

2+3.5i	A complex number

\19th Sept 88	A Date Object - the backslash defines it as a date

 A common mistake is to type a string omitting the quotation marks. A string such as Kacobs without the quotation marks is not a string object, but the name of a CleanSheet variable.


Sort Rows by Column n - The rows are rearranged in order that column n is sorted.

The first column is column 0, the second column 1 and so on. CleanSheet always refers to columns starting at 0, just as it refers to arrays starting at element 0.


Sort Columns by Row n - the columns are rearranged in order that row n is sorted.

The first row is row 0, the second row 1 and so on. CleanSheet always refers to rows starting at 0, just as it refers to arrays starting at element 0.


Search Object Contents Dialog
Search Object Contents

Introduction

This dialogue controls the search method used when searching through the contents of an object. The search action only applies to the Input Table objects - search locates the specified item and moves the insert point to that position.

This dialogue only appears during Use Mode.

The best approach to this is a step-by-step approach.

Step 1 - Enter the Data Item

Enter the item of data to search for in the Find field on this dialogue. This must be one of CleanSheets data types, for example "Smith" is a string type because it is enclosed in quotation marks.

It is a common mistake to omit quotation marks around strings, or to omit the backslash infront of dates. String must have the quotation marks ("Text" is a string, but text is the name af a variable within CleanSheet). Dates must have a backslash infront of them ( \9th April 74 is a date but 9th April 74 will result in a syntax error).

Step 2 - What to Look For

This section specifies what the Search is looking for, an exact match, the nearest match or a close match. Click on any part you need further help on.

Step 3 - Where to Search

This section allows you to limit where the search is made.

Step 4 - Where to Start

This section tells CleanSheet where to start the search from.

Step 5 - Start the Search

Select Find to begin the search. The dialogue remains open until you select Close, so if you need to repeat the search, click on Find again.

Objects Affected

Input Table


Exact Match - finds the object that exactly matches the search item. Exact match really means the = (equality) operator within CleanSheet. An exact match to a data item D has been found if Search_Item = D


Nearest - searches the Table to find the Nearest match for the search item, where nearest is defined by the Vague Logic Engine within CleanSheet.


%Vague Match - find an approximate match for the search item. How approximate a match depends on the value entered. 5 means between + or - 5% of an exact match. This comparison is done using the Vague Logic Engine within CleanSheet.


Search Whole Object - all the rows and columns of the table are searched.


Search Column - only the specified column is searched, CleanSheet columns, like CleanSheet arrays all begin with element 0, the first column is column 0, the second 1...


Search Row - only the specified row is searched, CleanSheet refers to the first row as row 0, the second row as row 1...


Start at Beginning - the search starts at the top left corner (row 0 column 0) of the table.


Start From After Insert Point - the start starts at the insert point - the element of the table that marks the current editing position.


Filter Type Dialog
Filter Type

Introduction

This dialogue controls the filtering done by a Filter Object. The action of a Filter Object is to go through an array, check each item piece-by-piece, items that match the filtering conditions are allowed through, items that don't are filtered out. This dialogue specifies the filtering conditions, and which section of the array to check during filtering.
A filter also works on single objects, each object that matches the filtering conditions is allowed through, each object that fails the filtering conditions is converted to a Null Object.

Part 1 - Filtering Conditions.

Click on any part that you need additional help on.

This section of the dialogue deals with the test applied to a data item to decide whether it should be allowed through the filter or be filtered out.

Start by selecting the Filter (for a list of available filter see Filters - List Of)

If Parameter A for the filter is constant, select the Check box next to Parameter A and enter the constant in the edit field.

If the filter requires Parameter B, set up parameter B.

For the Vague Filter Types, additional lower and upper limits of vagueness are needed, these are specified in the Vague Match section.

Part 2 - Which Part to Filter

This section deals with which section of the data is to be checked during filtering. Click on any part you need help on.

Example

You want to filter a two dimensional array such as {{"Jacks", "Jonas", "Jones", "Kacobs"}, {22, 8103, 102, 223}}. The array is a list of names and the scores that each of those people achieved.

Now you want to allow only people who scored greater than 200 through - filtering out the people with scores less than or equal to 200.

Select the filter type A < Data < B

Check the Box "Parameter A is fixed" and enter 200 in the edit field next to it.

Check the Box "Parameter B is fixed" and enter 1e100 in the edit field next to it.

Select "Compare Row by Row using Column 1"

The filter object will examine column 1 of its input pipe, check each item to see if it matches the test 200< Data <1e100 and if it does add the whole row to the answer.

The scores 8103 and 223 match the condition and so the output from the Filter Object is {{"Jonas","Kacobs"},{8103,223}}.

Objects Affected

Database Filter


Parameter A is Fixed - Parameter A refers to the 'A' in the filter type. If parameter A stays constant, then select the check box and enter the constant into the edit field.

If this check box is not selected, then Parameter A will be obtained from Input Pipe A.

The constant must be entered in as a CleanSheet data object. For example \12th June 79 is a date object because it has a backslash infront of it. See CleanSheet data types for more details.


Parameter B is Fixed - Parameter B refers to the 'B' in the filter type. If parameter B stays constant, then select the check box and enter the constant into the edit field.

If this check box is not selected, then Parameter A will be obtained from Input Pipe A.

The constant must be entered in as a CleanSheet data object. For example \12th June 79 is a date object because it has a backslash infront of it. See CleanSheet data types for more details.


Filter - The type of filter to use (a list of filters is available in Filters - List Of).


The Vague Match is the interval over which the vague filters pass data. The values refer to the result of a Vague Logic comparison. Such comparisons return values roughly in the range -100 to +100, with 0 being an exact match and +- 100 being a bad match.

The return of a vague comparison can be thought of as a percentage, hence a lower limit of -5 and upper limit of +5 would mean plus or minus 5% error.


Compare with Whole Object. The whole object be used for single objects, if the object meets the condition it is allowed through, if it doesn't then it's filtered out.

Notice that the first example fails because the test  400 < {{100,300},{200,150},{700,330}} < 800 is not true, i.e. the whole array is being tested in one go.


Compare Row by Row using Column n.

The nth columns is checked, each item that doesn't match the filtering conditions is removed, together with the whole of the row that it is in.

Remember - the first row is row 0.


Compare Element - by - Element.

This action applies to arrays, each column, and each row are tested separately, the items that pass the filter are retained, the items that don't pass the filter are discarded.


Compare Column by Column using Row n.

The nth row of each column is checked, if the item fails the filter test then the whole column is removed.

Remember - the first column is column 0.


Filters (list of)

The following is a list of filters available to the Database Filter Object within CleanSheet. For filter types with only one parameter such as A< Data , use the A < Data < B filter type and make B larger than any values you expect.

For example to create a filter of the type 400<Data, use 400 < Data< 1e100,

Data = A	Allows through data that matches Parameter A.

A < Data < B	Allows through only data greater than A, and less than B.

A <= Data < B	Allows through data that is greater than or equal to A, and less than B.

A <= Data <= B	Allows through data that is greater than or equal to A, and less than or equal to B.

A < Data <= B	Allows through data that is greater than A and less than or equal to B.

(Data = A) or (Data = B)
Allows through data that matches either A or B.

Data matches A within specified limits of Vagueness
The result of a Vague Logic comparison was between the Vague Lower and Vague Upper limits specified on the dialogue.

Data != A	Allows through data that does not match A.

(Data <= A) or (Data >= B)
Allows through data that is less than or equal to A, or greater than or equal to B.

(Data < A) or (Data >= B)
Allows through data that is less than A, or greater than or equal to B.

(Data < A) or (Data > B)
Allows through data that is less than A or greater than B.

(Data <= A) or (Data > B)
Allows through data that is less than or equal to A, or greater than B.

(Data != A) and (Data !=B)
Allows data that is not matched either to A or B.

Data is outside specified limits of Vagueness to A
The result of a Vague Logic comparison was outside the Vague Lower and Vague Upper limits specified on the dialogue.


Sort Type Dialog
Sort Type

Introduction

This dialogue sets the type of sorting done by a sort object. It is not connected to the sorting of an objects contents, for details of that see Sort Object Contents.

The sort object rearranges the order of an array into a sorted form, the exact definition of sorted is set by this dialogue.

Click on any part you need help on.

Example

If the input data to this object is a table of peoples names and scores, and you want to sort the table into descending order of scores.

The required order of sort is Descending.

The Sort Key is Sort Rows by Column 1 (remember that columns are numbered 0,1...).

Notice that column 1 is now in descending order, but notice also that column 0 has been rearranged so that the rows read across correctly.

Objects Affected

Database Sort


Ascending Order - The data is sorted, smallest first, largest last. The comparison used is the > (greater than) operator within CleanSheet. The rules that define if A>B control whether A goes before B or after it.


Descending Order - The data is sorted, largest first, smallest last. The comparison used is the < (less than) operator within CleanSheet. The rules that define if A<B control whether A goes before B or after it.


Nearness - How near each object is to the Comparison Object. Nearness uses the Vague Logic engine in CleanSheet to compare how similar two objects are. The data nearer to the comparison object is placed before the data that is further away.

To use this option you must enter the comparison data in Comparison Object.


Farness - How far each object is to the Comparison Object. Farness uses the Vague Logic engine inside CleanSheet to compare how similar two objects are. The objects that are less similar are placed before the objects that are closer.

To use this option you must specify a Comparison Object.


Comparison Object - Enter a CleanSheet data object into this field. This is used when the Order of Sort is either Nearness or Farness, this object is compared with each piece of data to decide which order to place them in.

The Comparison Object must be one of CleanSheet's data types.

For example \30th June 77 is a date object because it begins with a backslash character.

A common mistake is to omit the quotation marks from around string objects. "abcd" is a string object, but abcd is the name of a CleanSheet variable.


Sort Rows by Column n

The nth column is sorted according to the Order of Sort, the rows are also rearranged so that the elements of a row stay together during the sort.


Sort Columns by Row n

The nth Row is sorted according to the Order of Sort, the columns are rearranged at the same time to keep all the elements of each columns together.


Splice Type Dialog
Splice Type

Introduction

The Splice Type dialogue controls how a splice object joins two or more pieces of input data into a single output.

The splice is a simple joining together without any consideration of the data being merged. If you are merging two databases together using this object, there may be duplicate entries, when they are merged together both entries are kept. To merge two inputs together without duplicates use the Database Merge object.

If you aim to overlay several pieces of data at specific places in an array a better object to use is the Overlay Object.

Join Columns Together

The columns of the input data are spliced together.

For example two arrays {{100,300},{200,150}} and {{100,300,200}} would splice together to form {{100,300},{200,150},{100,300,200}}

Example: two dates are spliced together using column splicing. \18th June 77 and \19th June 77 to form the {\18th June 1977 , \19th June 1977}.

Join Rows Together

The rows of the input data are joined together. For this to work the two inputs must be arrays.

Example: Two arrays are merged by row. {{100,300},{200,150}} and {{500,300}} to form {{100,300,500,300},{200,150}}

Example: two arrays are merged by row: {{100,300},{200}} and {400,500} to form {{100,300,400},{200,NULL,500}}.

Notice the null added to keep the rows together.

Join into Array

If the input pipes are A, B and C, this option would return an array of type {A,B,C}. Notice that it promotes the the input data up by 1 dimension.

Example: if A is {100,200} and B is {{300,400}} the spliced result would be {{100,200},{{300,400}}}

The first piece of data goes from being a 1 dimensional row array to a two dimensional column array. The second piece of data goes from being a 2 dimensional column array into the third dimension.

Objects Affected

Database Splicer


Type of Array Chop Dialog
Type of Array Chop

Introduction

The Database Chopper, chops an array into uniform columns or rows. This dialogue control where the Chopper cuts.

For more complex or different breaking of arrays one of the following objects may be appropriate: Array Dissector, Database Trimmer, Database Extractor.

Chop into Columns

This mode splits arrays into columns starting at the specified column.

Example: The Array {{100,300,345,550},{200,150,750,640},{700,330,180,600}} is broken into columns {100,300,345,550}, {200,150,750,640} and {700,330,180,600}.

Notice that the array elements are demoted from a two dimensional array into 3 one dimensional arrays.

Example: The 1 dimensional Array {100,200,300,400} is chopped into columns to form the 4 numbers 100, 200, 300 and 400.

 If you need more that 8 column outputs, then use two of the Chopper objects and start the second one at column 8. Columns in CleanSheet are numbered beginning with 0,1.. and so on.

Chop into Rows

This option splits arrays into rows, starting at the specified row. This has no use when applied to 1 dimensional arrays, since a 1 dimensional array is in effect a single row.

Example: The two dimensional array {{100,300,345,550}, {200,150,750,640}, {700,330,180,600}} becomes 4 single dimension arrays {100,200,700} {300,150,330}  {345,750,180} and {550,640,600}.

Notice that Chopping arrays demotes them by 1 dimension. The input was two dimensional, the output is only 1 dimensional.

 If you need more that 8 row outputs, then use two of the Chopper objects and start the second one at row 8. Rows in CleanSheet are numbered beginning with 0,1.. and so on.

Objects Affected

Database Chopper


Set Extraction Section Dialog
Set Extraction Section

Introduction

This dialogue sets the area to extract for a Database Extractor object. The extractor takes a two dimensional input array and extracts a single sub-array from it.

For more complex extractions, or multiple extractions one of the following may be more appropriate: Array Dissector, Database Chopper, Database Trimmer.

The Area to Extract consists of a rectangle whose top left and bottom right corners are specified. That section of the input array is cut out and sent to the output of the extractor object.

Left	The Column that the left edge is at. Columns are numbered starting from column 0.

Top	The Row that the top edge is at. Rows are numbered starting at row 0.

Right	The Column that the right edge is at. The right edge can be set to the right edge of the input data, simply by selecting "Right Edge of Input".

Bottom	The Row that the bottom edge is at. The bottom edge can be set to the bottom of the input data by selecting the "Bottom Edge of Input" button.

Example

An area {1,2} to {Right Edge of Input, 3} is extracted from the array {{10,11,12,13,14,15}, {20,21,22,23,24,25}, {30,31,32,33,34,35}, {40,41,42,43,44,45}}. The results is the sub array {{22,23},{32,33},{42,43}}.

Objects Affected

Database Extractor


Curve Fit Type Dialog
Curve Fit Type

Introduction

The curve fit object fits an equation to a set of data points. There are several different curves it can fit and this dialogue selects which.

Choose the curve that you think the data best represents. If the data is approximately a straight line then select straight line, if it's exponential choose an exponential curve, if its an x^2 curve then choose the x^2. If the data has no obvious simple representation the choose a Polynomial Curve of suitably high order.

Straight Line

When this option is selected, the Curve Fit object will return an equation of the form 'mx+c' where m is the gradient of the line and c the intersection with the y axis.

Exponential Curve

When this option is selected, the curve fit object will return an equation of the form be^x where b is the constant for the curve and e is the constant 2.7182818...

This type of curve is used when the data represents some form of exponential growth.

x - Square Curve

With this option selected, the curve fit object fits an equation of the form bx*x where b is the constant for the curve.

This type of curve fit is faster and less prone to error than a polynomial fit, but notice that this is just a special case of the 2nd order polynomial.

Polynomial Curve

With the polynomial curve option selected, the curve fit object generates an equation of the form a+bx+cx^2+dx^3+... where a, b, c, d... etc. are the constants for the curve.

The order of the polynomial is the number of terms it produces+1. For example the order 2 will produce an equation a+bx+cx^2, order 3 produces a+bx+cx^2+dx^3 and so on.

The more terms in the polynomial, the more twists it can make.

The number of unique data points must be greater than the order of the polynomial.

Higher order polynomials involve a great deal of computation and hence a great deal of accumulated rounding errors.

If the point lies along a simple curve, but with slight measurement errors in the data points, then choosing a high order polynomial may simply create a curve attempting to approximate the errors rather than the underlying curve.

Choose the lowest order polynomial you think suits the data.

Objects Affected

Curve Fit Object


Conversion Type Dialog
Conversion Type

Introduction

The Converter object converts one type of input to a different type. The actual conversion is done by a superset version of the make{} function within CleanSheet.

There is only one thing to select on this dialogue - the type of conversion to perform.

For a list for CleanSheet data object types see Data Types.

Conversions

Convert Array to String	The array is converted to a string representation of itself.
Example: {12,{10,20},20} converts to a string "{12,{10,20},20}". It may look the same, but the first is an array with four elements, the second is a string of 15 characters.

Convert Input to Integer(s)	Converts the input to integer types. Numbers are truncated, equations and strings are evaluated, then converted. An array input will have each element converted to integer types separately and the result returned as an array of the same form.
For example, 23.5 becomes 23@

Convert Input to Float(s)	Converts the input to single precision floating point numbers. An array put through this conversion has each element converted separately and the result is a returned array of the same type. String and equations are evaluated to produce a result and the result converted to a float.

Convert Input to Double(s)	Converts the input to double precision floating point numbers. An array converted in this way has elements element treated separately, the result being an array of the same form. Strings and equations fed through this conversion are evaluated and the result converted to a double.
For example 23+3i becomes 23.

Convert Input to String(s)	Converts any input data objects into string objects. Equations are detokenised, other objects are converted using the Number Format, Time Format, Date Format or Complex Number Format set for this object.

Convert Input to Boolean(s)	Converts numeric values to TRUE if they are not zero and FALSE is they are zero. String and equations are evaluated to produce a numeric type and then converted. Arrays are treated element by element.
For example 12.3 become TRUE

Convert Input to Date(s)	Converts the input data into date objects. Numeric objects are taken as days since 1900 and converted accordingly, string and equations are evaluated to other objects types then converted. Arrays are treated element by element.
For example 34180@ becomes \1st August 1993

Convert Input to Time(s)	Converts the input data into Time Objects. Numeric objects are taken as seconds since midnight and converted accordingly. Equations and string are evaluated and the result converted. Arrays are broken into elements and each element treated separately.
For example 75.3 becomes 00:01:15

Convert Input to Complex(s)	Converts data in the input into Complex Numbers. Numeric object have an imaginary part of zero appended to make them complex. Time Objects are converted to seconds since midnight and then converted, Date objects are converted to days since 1900 and then made complex. Arrays are taken element-by-element, the conversion being applied separately to each.
For example: {2.3, 00:01:15} becomes {2.3+0i , 75+0i}

Convert Input to Equation(s)	Tokenises string objects into the equivalent equation object. An array fed through this conversion has each elements treated separately to return an array of equation objects.

Evaluate String/Equation	When converting an object to a different type string objects and equation objects are first evaluated, then the conversion is done to the result. This conversion type only does the first part, the equations and strings are evaluated and whatever type results is returned.
For example "sqrt(2)" become the complex number 0-2i

Objects Affected

Converter


Data Lookup Type Dialog
Data Lookup Type

Introduction

The Data Lookup Object, looks up the values from one list in another list. Implicit in this action are three steps: How to reference the data, where to reference the data, and what to do when a match is found. This dialogue sets those 3 actions.

Note that it is Input Pipe A that is being looked up in Input Pipe B.

When an array of items is fed into input pipe A, each element is treated separately and the result is an array of the same form, with each elements converted by the lookup process. This is multiple data lookup, and has many uses. For example, it could be used to convert a table of pay grades for a group of workers into the actual annual salaries of those workers, looking up the salary that corresponds to each grade of pay.

Step 1 - How to Look

The method used to match an entry in the list - is it searched for? or is it a number that can be referred from the list? - this section decides which.

Click on the option you need further help on.

Step 2 - Where to Look

This section restricts the part of B that will searched when looking for a match.

Click on any part you need further help on.

Step 3 - What to do When Found

This section deals with the action to take when a match is found, click on any option you need help on.

Example

You have a table of raw retail prices that need to be converted. For this example we only want retail prices that are magic price points (for example 2.99, but not 3.00, 9.95 but not 10). So we need to convert from the raw retail prices to their nearest magic price.

The option we select to do this are:

Find the nearest Match to Item A

Look Through Whole Object

Output Only the Data

Objects Affected

Lookup Object


Index into the list to get the Ath entry.

Assuming that input pipe A is a number and B a list, element A from list B is returned as the output from the Lookup Object.

CleanSheet elements begin at 0.

Example

Here the pipe A is indexing into the columns of Pipe B to return its contents. Notice that since Pipe A is an array, each element is treated separately.

Notice that a Null is placed where the 7 was. This is because there is no element 7.


Find the entry that matches Item A

List B is searched until a match is found for item A. For a match to be made, the equality condition must be met (using the = operator). This means for example that 2@ = 2.0 and that "Text String" = "text string".

Example

If the whole of B is being searched for a match for item A and the result TRUE returned if a match is found.

Notice that since input A is an array, the lookup process is repeated separately for each element. In this example only the 12 could not be matched.


Find entry that matches Item A within % Vagueness N

Search the specified part of item B for a approximate match for A. Approximate as defined by the CleanSheet Vague Logic Engine - if the value returned by a vague comparison is within +- N then a match has been found.

When this option is selected, you should enter the value of the vagueness allowed N. Smaller values, closer to zero mean a closer match.

Example

If the whole of B is being searched for an approximate (10%) match for item A and the result TRUE returned if a match is found.

Notice that since input A is an array, the lookup process is repeated separately for each element. Here everything was matched, even the 12 which was close enough to 12.3 to pass the vague comparison.


Find Nearest Match to Item A

Input B is searched for the nearest match to Input A. Nearest is defined by the CleanSheet Vague Logic Engine, the result of each comparison is checked, the value closest to zero indicates the nearest object.

Example

The nearest match for Input A is being looked for in the row of Input B.

Since Input A is an array, each element is processed separately to obtain the nearest match to each.


When a lookup object is retrieving a record from a database, only one field of each record needs to be checked. If records are column and fields are rows, then you could have examples such as the following:

In this example, only the second row needs to be search, so Where to Look would be set to "Look in Row number 1".

Rows are numbered 0,1,2... in CleanSheet.


Often the Lookup object is retrieving a record from the database based on a key. Consider the example.

Only the first column needs to be examined, so Where to Look would be set to "Look in Column Number 0"

Columns in CleanSheet are numbered 0,1,2...


Look Through Whole Object

When this option is chosen, all the rows and columns of array B are searched to find a matching object.

Consider the above example, the Lookup Object searches the whole of the array to find a match.


Output the Row Containing the Data

The Row of data the match was found in is returned as a 1 dimensional array.

If no match is found a NULL object is returned.


Output the Column containing the Data

The Column that the match was found in is return as a 1 dimensional array.

Note that 1 dimensional arrays appear as a row.

Example:

If no match is found a NULL object is returned.


Output Only the Data

The item of data matched is returned, or a NULL if no match is found.

Notice that a string object is returned not a 1 dimensional array of strings {"Clubs"} or a two dimensional array of strings {{"Clubs"}}.


Output TRUE

If a match is found then a TRUE is returned, if no match is found then a FALSE is returned.


Counter Type

Introduction

The counter object counts the rows, columns or items in the input data - this dialogue specifies which.

Count the Rows in the Input Data

The return from the counter object will be the maximum number of rows in the input.

Count the Columns in the Input Data

The number of columns in the input data is returned.

Notice that inputs that are not arrays are treated as 1x1 element arrays and hence have 1 column.

Count the Number of Items in the Input Data

Counts the number of elements that are not arrays in the input item.

Include Null Items in the Count

When this is selected, columns and rows that contain nothing but nulls are included in the count, similarly the null items themselves are included in the Items Count.

Objects Affected

Counter


Hard Copy Settings

Introduction

The Hard Copy object prints data out as a table in a similar way to the Output Table object displaying data onto the screen. This dialogue controls the option specific to that object.

Print Using Array Notation

Normally the first two dimensions of any input data are expanded and the input is printed as a table. If this option is selected, then the data is printed in CleanSheets array notation.

For example:

Print to File

With this option selected, data is printed to a disk file rather than sent to the printer. The disk is not normally readable. If you need a disk representation of the data for editing or importing into other packages, use the Filing Clerk object.

This option has no connection to the Printer Manager. To invoke the Print Manager to spool the printout to disk, use the Windows Control panel.

Percentage Scale

Sets the scaling for the printout. 100% scales the display at the same size as the screen, a lower value makes the printout smaller, but more can be fitted onto a page.

Page Layout

The margins, headers and footers for each page are set by this dialogue. The page layout details are kept with the Hard Copy object, so that each object can have a different set of headers and footers.

Objects Affected

Hard Copy Object


Filing Clerk Settings Dialog
Filing Clerk Settings

Introduction

The filing Clerk sends the input it receives to a file on disk. The file is a text file that can be read by other programs or edited with a Windows Notepad. If the file on disk is intended to be formatted for the printer, it is better to use a Hard Copy object and select the Print To Disk option.

This dialogue sets the options for the filing clerk object.

Use Array Notation

The input data is converted to a string and that string is written to the file. CleanSheets array notation is used, .e.g. {12, 2.34} is a 2 element array.

Expand Column Data - Comma Delimited

This is useful when the input to the Filing Clerk is an array. The array is expanded and converted to comma delimited ascii form. This is a common interchange format between applications.

Each column is separated by a comma and each row by a Carriage Return/Line Feed character.

Notice also that text strings are enclosed in quotation marks, while numbers aren't.

Expand Column Data - Tabbed Columns

With this option selected, arrays input into the Filing Clerk are expanded with tabs between columns and Carriage Returns/Line Feeds between rows.

Notice that unlike comma delimited Ascii, strings are not in quotation marks.

Append Data to End of File

When this option is selected, the data to be filed to disk is appended onto the end of the file. Each recalculation appends more data onto the file.

When you select OK on this dialogue, the file is cleared and a new file started afresh. Selecting this option does not change that.

Recreate File Each Run

Each time the sheet is recalculated, the file is created and the result written to the file. The file will only ever contain one generation of the data - the latest version.

File

Before exiting this dialogue, you should also set the file name to write the data to. If you do not, then no data will be written.

Objects Affected

Filing Clerk Object


Merge Type Dialog
Merge Type

Introduction

The Merge Object, merges two arrays (arrays representing databases) together, using a specified system. This dialogue specifies how the merge is performed.

Combine List A and List B

The output from the Object is the combined result of the two lists, but with duplicates removed. This is illustrated by a Venn Diagram:

 if the two input arrays have no duplicates it is faster and simpler to use a Splice object to simply join them together.

Only allow Items from List A that are Not Present in List B

Use this option to exclude parts of list A. Its Venn diagram is:

Consider an example: Array A is a list of male employees and Array B is a list of all employees (male and female) who have received bonuses. To produce a list of male empolyees who have not received bonuses, you would use this option.

Only allow Items from List A that are also in List B

The Venn diagram for this option looks like this:

Notice that it is the intersection of the two lists. If Array A contains the list of male employees and List B contains the list of all employees who have received bonuses, then this option would produce a list of male employees who have received bonuses.

Only allow Items not in both lists

The Venn diagram for this option looks like this:

If Array A contains a list of male employees and Array B contains a list of employees of both sexes who have received bonuses, then this option would produce a list that employees that either never receive a bonus, or are female.

Check Row-by-Row

This option specifies that the database records are rows of the arrays. For example a list of employees and their test scores could look like this:

Check Column-by-Column

This option specifies that the database records are columns in the arrays. A list of empolyees and their test scores could look like this:

Objects Affected

Database Merge


Switch Connections Dialog
Switch Connections

Introduction

A Switch Object routes input pipes to output pipes according to a control value. This dialogue specifies which pipes are connected to which for each control value.

For example consider a switch with 3 states as follows:

This is a typical switch object with 2 inputs and 2 outputs.

When the data coming in to the control pipe is zero, the first expression is true and so the connection A to A is made. Output B is not connected and has the value NULL.

When x>0, input B is connected to output B. Output A has a NULL value because it is not connected.

When x<0, input A is connected to output B and input B is connected to output A. Whatever data is fed into input A in this state appears at output B.

What you should particularly learn from this example is that the control expressions are always functions of x, that disconnected outputs have a Null value, and that the control expressions can be anything. For example InPolygon{x,{{10,20},{30,40},{10,50}}} is a valid expressions - it uses the InPolygon function to test if the point x is within the polygon (10,20) to (30,40) to (10,5). Any expression that can be used as a TRUE/FALSE test can be used in a switch object.

Click on any part you need help on.

Preparing a Switch Object Step-by-Step

1	Set the Number of Inputs and Outputs. For the example above this was 2 inputs and 2 outputs.

2	Clear the Control Expressions of any old, unwanted expressions.

Select an expression to be deleted

Select 'Delete from List' button

3	Add the new control expressions one by one.

Type in an expression to be tested

Select the Add to List button

Drag lines from the Inputs to Outputs to represent the links

Objects Affected

Switch Object


The number of inputs into the switch. This does not include the control input x, which is always there.


The number of outputs out of the switch.


Control Expressions - this section deals with the expressions that are tested when deciding the state of the switch. Each expression is evaluated starting at the top of the list and working down. When an expression evaluates to TRUE, the corresponding set of switch connections is used.

The first expression that evaluates to TRUE is used, even if there are several expressions that are TRUE.


Control Expressions - enter the expression to be evaluated for a switch condition.

Expressions refer to the control input 'x', any CleanSheet function or operator can be used. Similarly the expressions need not evaluate to TRUE or FALSE, 1 or 0 would equally do.

x=10
x>100 & x<500
x>"London"
InPolygon{x,{{10,20},{30,40},{10,50}}}

10+3 (x is omitted)
x*x+1 (could never be FALSE)

For a list of CleanSheet functions and operators see General Operators.


Add to List

Adds the expression and the associates links to the switch states list.

Adding a new State

Enter the expression that tests for the state.

Select 'Add to List'

Link the inputs to the outputs in the links section


Delete from List

Deletes the selected expression from the list.

Select an expression to be deleted

Select 'Delete from List'

The associated switch links are also deleted


Change

Changes the links and control expression for an entry in the links table.

To Change a Switch State

Select the expression to edit from the list

The links are displayed in the links section and the expression in the edit field.

Edit the expression and links

Select 'Change'


This is the list of control expressions that correspond to each state of the switch. Select any of these expressions to display its links in the links section.


Links

This section displays and edits the links that correspond to a switch state.

Adding a Link

Using the mouse, click on an input spot and drag a line over to an output spot. Then release the mouse button. The link will be formed.

Deleting a Link

Click on the output spot that the link is joined to. There can only be one connection to an output, so CleanSheet will break that link.

Move the mouse to where there are no spots to join to.

Release the mouse button

The link will remain broken.

Moving a Link

Click on the output spot the link connects to. The link will break.

Move the end of the link to the new output.

Release the mouse button, the link will form to the new output spot.

If you wish to move an input spot, you must delete the link and remake it.


Random Input Dialog
Random Input

Introduction

The random input object is used to pump random input data into a sheet. This dialogue controls that object.

When to Recalculate

This section deals with recalculation of the random input. The recalculation mode also affects how this object is recalculated.

Every Recalculation of Sheet

Whenever the sheet is recalculated, either manually or automatically, the function is recalculated to generate a new random output.

When Object is Pressed

With this selected, the output value remains the same until the button on the Random Generator object is pressed.

With this option set and the sheet switched to automatic recalculation, clicking on the random button will cause a recalculation of the sheet.

When Object is Pressed AND Sheet Recalculated

With this option, the random output remains constant until the Random Generator button is pressed. However, even if automatic recalculation is switched on, clicking on this button will not cause a recalculation.

This is useful when there are several random inputs. Click on each Random Generator Objects whose value is to be changed, then click on the Manual Recalc button to recalculate the sheet.

Random Equation

This section contains the equation that is evaluated to generate a random number. Normally the Rand function is used. This function generates random numbers between 0 and 1, but equations based on this can generate a whole range of random numbers.

Examples

Rand * 100	Generates random numbers 0 to 100

Rand * 100+100	Generates random numbers 100 to 200

Rand*365+\1st Jan 1993	Generates random dates from the year 1993

Rand>0.5	Generates random TRUE/FALSE Boolean values

You need not use Rand to generate the output, any function whose value changes could be used.

Examples

Now	Returns the current time

today	Returns the current date

By using a local object variable, you can create a counter using the Random Generator Object. For example the function ls_a:=ls_a+1 will have an initial value 1, and each time this function is generated, the value will increase by 1. This is because the value is saved in an object variable ls_a (see Variables and their Scope).

Objects Affected

Random Generator


Toolbox Dialog
Toolbox

Introduction

The toolbox dialogue sets which tool to use for a General Toolbox object, Statistical Toolbox object and Financial Toolbox object.

Although this dialogue is the same for all 3 toolbox type, they appear separately for each toolbox and affect only the toolbox objects that are the same type.

Toolbox objects take only 1 input. This is important because, used properly, they can simplify a sheet. However if you have several inputs, you could actually make you sheet more complex by having first to join the inputs together, then calculating with the toolbox object, then breaking the result down again with a third object. Under those circumstance, it is better to use a normal Calculator Object.

Step 1 - Transpose

Transpose the Data - Selecting this make rows into columns and columns into rows. If the toolbox function requires a column array and the input is a row array, they select this button to transpose it.

Step 2 - Removing Headers

Your input data may have column or row headers which need to be removed before use. Select 'Strip off first row' or 'Strip off first column' to remove the first column or row heading.

If you transposed the data at Step 1, then you also made the first column into the first row and the first row into the first column.

Step 3 - Toolbox Calculation

Select the toolbox calculation to perform. This list varies according to the type of toolbox object. For details see General Toolbox Functions Listed, Financial Toolbox Functions Listed, and Statistical Toolbox Functions Listed.

Step 4 - Appending Result

This section deals with attaching the original data and re-attaching the column and row headings that were removed.

Append Result to Input

If the result is a column, then it is appended to the right edge of the input data.

If the result is a row, the it is appended to the bottom edge of the input data.

ReAppend First Row

The first row (the column headings) that was removed at step 2 is re-appended.

ReAppend First Column

The first column (the row headings) that was removed at step 2 is re-appended.

Step 5 - Transpose the result

The result of step 4 can be re-tranposed if this option is selected.

Objects Affected

Toolbox - General

Toolbox - Financial

Toolbox - Statistics


General Toolbox Functions

The general toolbox contains common summations and sum-product operations that are performed on a single array. For multiple inputs, a more appropriate object might by the Sum Object or the Sum Product Object.

Column Multiply

The first two columns are multiplies to generate a third column with corresponding rows multipled together,

The normal CleanSheet multiplcation operator is used, hence 2* "Ab" results in "AbAb".

Column Multiply and Sum

The first two columns are multiplied and the resulting column is then summed and the sum appended onto the result.

The finished result is the products of the columns with the total at the bottom.

Sum of Column Product

The first two columns are multiplied and the resulting column summed. Unlike the previous example the return is only the total.

Notice that the returned value is the single value 84.7, not the array {84.70} or the two dimensional array {{84.70}}

Rolling Sum

Calculates the rolling sum of a column.

As you go down the column, each new entry is added in.

Sum of Rows

The rows are summed across to produce a column as a result.

Sum of Columns

The columns are summed down to produce a row as a result.


Financial Toolbox Functions

The financial toolbox contains the financial functions within CleanSheet. The exception is the Savings and Loans function SAL which is sufficiently powerful to warrant its own object (see Savings and Loans Object).

If you do not need all the preprocessing, transposing and reappending of a Toolbox object, then you could equally use the normal Calculator object with the appropriate function typed into it.

Functions Available

Future Value (FV) of an Investment or Loan - Example.

Present Value (PV) of an Investment or Loan - Example.

Periodic Payment (PMT) of an Annuity - Example.

Interest Portion of Payment (IPMT) - Example.

Principle Portion of Payment (PPMT) - Example.

Number of Periods (NPER) - Example.

Interest Rate (Rate) - Example.

Straight Line Depreciation (SLN) of an Asset - Example.

Sum of Years Digit Depreciation (SYD) of an Asset - Example.

Double Declining Balance Depreciation (DDB) of an Asset - Example.

Partial Period Depreciation (VDB) of an Asset - Example.

Internal Rate of Return (IRR) for a Series of Cashflows - Example.

Net Present Value (NPV) For a series of Cashflows - Example.


Statistical Toolbox Functions

The statistical toolbox is an object level implementation of CleanSheets statistical function.

If you do not need all the preprocessing, transposing and reappending of a Toolbox object, then you could equally use the normal Calculator object with the appropriate function typed into it.

Functions Available

Mean	Mean (average) of values.

Median	Middle value of range of values.

Sample Deviation (StDev)	Standard Deviation from a sample of a population.

Standard Deviation (StDevP)	Standard Deviation from the whole of a population.

Sample Variance (Var)	Variance from a sample of a population.

Variance (VarP)	Variance from the whole of a population.

Minimum Value (Min)	Minimum value of input values.

Maximum Value (Max)	Maximum value of input values.

Sum of Squares (SumSqr)	Sum of Squares of input values.

Sum of Values (Sum)	Sum of all Numeric Values.

Combinations	Combinations of r from n input as {n,r}, e.g. Combinations of 2 taken from 4, {4,2} returns 6.

Permutations	Permutations of r from n input as {n,r} e.g. Permutations of 99 from 100, {100,99} returns 100.


Content Alignment Dialog
Content Alignment

Introduction

This dialogue controls the alignment for Text and Data Input objects. The text for these objects consists of a block and hence has a vertical aswell as a horizontal alignment. This dialogue does not handle the table object such as the Input Table and Output Table objects, which are covered by the Alignment of Text dialogue.

Horizontal Alignment

Left	Align the block of text to the left edge.

Middle	Align the block of text centrally horizontally.

Right	Align text flush to the right edge.

Vertical Alignment

Top	Aligns the block against the top edge.

Middle	Align the block of text centered vertically.

Bottom	Align the block of text against the bottom of the object.

Objects Affected

Object Input

Text Box


Paste Function Dialog
Paste Function

Introduction

The paste function dialogue allows you to select from a list CleanSheets functions, rather than type the function in directly. This dialogue also displays the correct parameters for the function and will use the correct brackets ( ) or { }.

The main purpose of this dialogue is to make entering functions into CleanSheet less error prone, but it is also a useful reminder of what parameters a function takes.

This dialogue is only available when an the cursor is in an edit field that requires CleanSheet functions. Otherwise the Paste Function dialogue is disabled.

When you wish to paste another function as a parameter to the first, click on the Paste Function.., another copy of this dialogue will appear.

If you want Help on the selected function, use the Help on Function button.

The Paste Input button is only enabled when this dialogue is selected from the Cog Type dialogue. The Paste Input button is the same as the Paste Input button on the Cog Type dialogue.

Example of Paste Function

We are entering an equation to enter the current date as a string object into the edit window.

Select Paste Function

Select Make from the list

Place the cursor in the edit field labeled Source Object

Select the Paste Function button - another copy of this dialogue will appear.

Select today from the list of the 2nd Dialogue.

Select OK - the second Paste Function dialogue will close

Place the Cursor in Destination Object

Select Paste Function - a second copy of the dialogue will open

Select FormalDateForm

Click on OK - the second dialogue will close

Click on OK on the first dialogue to insert the equation.

You now have the correct expression make{today,formaldateform} which will correctly get the current date and convert it to a string in formal date format.

See Also

General Functions, Listed

Geometric Functions, Listed

Trigonometric Functions, Listed

Array Manipulation Functions, Listed

Financial Functions, Listed

Statistical Functions, Listed


Dissector Outputs

Introduction

The Dissector Object breaks arrays into multiple fragments. One array goes in, up to 36 fragments come out.

This dialogue specifies where the fragments are taken from and whether they are produced as 1 single items, 1 dimensional arrays or two dimensional arrays.

There is a much simpler, easier to learn object which extracts single sections from arrays. If you need to extract only a single fragment, returned as a two dimensional array then use the Database Extractor Object.

The right side of this dialogue has been cropped for compactness, click on any part that you need help on.

To Break an Input Array into Fragments

Enter the number of outputs (fragments) required.

Working Through each fragment one-by-one

Select the fragment name (A,B,C....0,1,2..9) from the Output list

Select the top, left, right, bottom corners of the area to extract

Select whether the result is to be a 2 or 1 dimensional array or not an array at all.

Click on OK.

Instead of entering the numbers for top, left, bottom, right you can use the mouse in the right hand section to highlight the selected area.

If the sheet has been recalculated and hence there is data being fed into this object's input pipe, then this dialogue will display that input in the right hand section. You can then get a much better idea of the section of the array you are extracting.

Objects Affected

Array Dissector


Number of Outputs - The number of fragments that are to be produced. Each fragment appears at a different output on the Dissector Object. A is the first, B the second to Z the 26th, from then on the outputs are numbered 0,1,2 to 9.


Output - the output (fragment) whose settings are being edited. All editing of the area and array types refer to the selected output and only the selected output.


Left - the left column of the section of the array that will be extracted. Columns in CleanSheet are numbered starting from zero.


Top - the top row of the section of the array that will be extracted. Rows in CleanSheet are numbered starting from zero.


Right - The right column of the section to be extracted. Columns in CleanSheet are numbered starting from zero.

The column for the right edge is included in the section being extracted. For example Left 0 Right 1, extracts columns 0 and 1.


Right Edge of Input - with this selected, the right edge of the fragment will as wide as the right edge of the Input array.

For example if the left edge is zero and right edge is 'Right Edge of Input', then the whole width of the input array will go to the output, regardless of how wide the input array is.


Bottom - The bottom row of the section to extract. Rows in CleanSheet are numbered starting from zero.

The bottom row is included in the extract area, for example if you extract top 1 to bottom 2, both rows 1 and 2 are extracted.


Bottom Edge of Input - The bottom edge of the section to extract is taken as the bottom edge of the Input Array. This is useful when you don't know in advance how many rows are in the input array.


Output as a Single Item

When a section is extracted from a two dimensional array, it is two dimensional, even if it consists of only 1 element.

Example, {{2.3}} is a typical extracted elements.

Output as a Single item, removes the first two levels of arrays from the result to produce the number 2.3.

This option will always take the top left element from the result, for example {{1,2},{3,4}} will become 1.


Output as a 1 Dimensional Array

When sections are extracted from two dimensional arrays, they are two dimensional.

For example {{2.3,4.5}} is a column of 2 elements.

Output as a 1 Dimensional Array removes the top depth of arrays from the result producing in this case {2.3,4.5}. Notice that this is now a row of 2 elements (1 dimensional arrays are always rows).

This option flattens an array to 1 dimension, for example {{1,2},{3,4}} becomes {1,2,3,4}.


Output as a 2 Dimensional Array

When fragments are extracted from a 2 dimensional array, the result is always a two dimensional array.

For example {{1,2},{3,4}} is a 2 by 2 array.

This option leaves the fragment unchanged.


Display Section

This section shows the size of the fragment being extracted. If the sheet has been recalculated, then this section displays the contents of the input pipe into the Dissector Object.

To Select an Area

Click with the mouse at the top left corner of the section to extract.

Drag the mouse to the bottom right corner of the section to extract.

Release the mouse button.

If you drag to the far right or far bottom of the Display area,
then this is taken to mean the Right Egde of the Input,
or the Bottom Edge of the Input.

To Select a Column

Double click in the centre of the column.

To Select a Row

Double click at the edge of a column.


Title

Introduction

Objects Affected


Reporter Type Dialog
Reporter Type

Introduction

The Reporter object assembles the input data it receives into an array. In effect it reports the inputs it receives. It is used together with one or more Announcer Objects.

In assembling the data into an array there are two possible ways, this dialogue selects which.

Assemble Column-by-Column

The data is strung together into columns.

The first set of data in becomes the first column.

Assemble Row-by-Row

The data is strung together into rows.

The first iteration becomes the first row.

Objects Affected

Reporter Object


Announcer Type Dialog
Announcer Type

Introduction

The Announcer object takes an input array and announces it column by column or row by row to a section of sheet bracketted by an Announcer/Report object pair. This dialogue specifies how the announcing is done. (See Also Reporter Object).

Announce Column-by-Column

The data is split into columns and announced one column at a time.

The first column is announced first.

Announce Row-by-Row

The data is split into rows and announced one row at a time starting at the first row and working down until all the rows have been announced.

Objects Affected

Announcer Object


Overlay Inputs Dialog
Overlay Inputs

Introduction

The Overlay object lays several inputs over one another to form a two dimensional output array. Several inputs go in, one output comes out. This dialogue controls the area of the finished array that each input fragment overlays.

Click on any part of the dialogue you need help with. This illustration is cropped to make it more compact.

Preparing an Overlay Object

Enter the number of inputs to be merged

For each input, one-by-one.

Select the name of the input (A,B...Z,0,1)

Enter the top, left bottom and right columns and rows of the array that the input will overlay

Click on OK

You can choose to enter the coordinates of the overlay area by using the mouse on the right hand section of this dialogue.

If the sheet has been recalculated and hence there is data in the pipes in to the overlay object, then this dialogue will display a simulated result. This makes it easier to visualise the finished two dimensional array.

Example

If there are two inputs into the Overlay Object, A - a 2 dimensional array and B a 1 dimensional row (1 dimensional arrays are always represented as rows).

Area covered by A is Left 0, Top 0, Right 1, Bottom 1

Area covered by B is Left 1, Top 0, Right -right edge of input, Bottom - Bottom Edge of input.

Notice that Input A has a higher precedence than Input B and hence where they overlap the value comes from Input A.

Objects Affected

Overlay Object


Select the input whose settings are to be edited.


Number of Inputs - Enter the number of inputs (fragments to be overlaid) in this edit field.


Left - The left column of the area the input is overlaid onto. Note: CleanSheet columns are numbered beginning with zero.


Top - The first row that the input will be overlaid onto. Note CleanSheet rows are numbered beginning from zero.


Right - The rightmost column of the area overlaid by the input data, note that this column is included in the area.


Right Edge of Input - with this selected, the data will continue to be overlaid for the full width of the input data.

If the input data is 4 columns wide, and the Left is set to 1, then the data will be overlaid over columns 1,2,3 and 4.


Bottom - The bottom row over which the data will be overlaid. The row specified is included in the affected rows.


Bottom Edge of Input - With this option selected, the data continues to be overlaid until the bottom edge of the input data is reached.


Display Section

This section shows the size of the fragment being overlaid. If the sheet has been recalculated, then this section will also display a representation of what the result will look like.

To Select an Area

Click with the mouse at the top left corner of the section.

Drag the mouse to the bottom right corner of the section.

Release the mouse button.

If you drag to the far right or far bottom of the Display area,
then this is taken to mean the Right Egde of the Input,
or the Bottom Edge of the Input.

To Select a Column

Double click in the centre of the column.

To Select a Row

Double click at the edge of a column.


Find Dialog (Within Editor)
Find

Introduction

This dialogue finds a matching text string within the CeSk program editor. Enter the text string to be found and select the Find button, the editor will search for a matching string and highlight that section. The dialogue remains open, if you need to find the next occurrence simply select the Find Next button.

Find is not case sensistive ("TEXT" = "text") because the CeSk programming language is not case sensitive.


Inspect Variable Dialog
Inspect Variable

Introduction

When running a program in the Computer Object, if the edit window containing the program is left open, then CleanSheet goes into program debugging mode. In this mode it highlights the lines of code being executed and displays a variables tracking window listing the variables available to the program. This dialogue is the Variables Tracking window.

On the left of the dialogue are 3 identical sections for displaying the contents of variables. On the right section are the controls to how the program is executing.

Click on any part of the dialogue you need further help with.

Variables are only shown if they exist. If you program has not yet reached the point at which a variable is specified then it does not yet exist and will not be in the list.


Group - The group of variables be examined. Selecting this lists all the variables belonging to that group in the Variables list. The groups correspond to the prefixes that variables can have.

Variables with no prefix for example are Automatic variables that are only maintained for a single function.

g_ variables are global to the sheet which means any variable in this group is shared between all objects on the sheet.

For details on the groups of variables see Scope of Variables.


Variable - The variable whose value is to be shown is selected from this list. Only the variables that exist at this point in your CeSk program are listed - if your program has not yet assigned a value to a variable, then it may not exist and you may have to continue executing the program past the line that initialises it.

Only the variables from the specified group of variables is listed.


The contents of the specified variable are listed in this section. The display is done using CleanSheets array notation, so a 1 dimensional array might look like this {1,2,3} and a single string might look like this "Text".


Continue - When execution of the program is paused, selecting this button continues execution where it left off.


Pause - Suspends execution of the program until the Continue button is selected. It is useful to pause the program to setup your variable tracking window.


Stop - Stops execution of the program. The Computer Object running the program will report an error indicating that its program was stopped by the user.


Speed - The speed of execution of the program is set by this scroll bar - Faster to the left, slower to the right.

If you need to speed up execution and you do not need to see the program running, then minimise the editor window. The lines being executed will not be highlighted and hence the program will execute faster.


Constraints Dialog
Constraints

Introduction

The Solution Search object searches for a solution to a sheet, subject to constraints that limit it. This dialogue sets those constraints.

A constraint is a rule that must evaluate to TRUE for the constraint to be met. For a valid solution all the constraints listed in this dialogue must be met.

Click on any part of the dialogue that you need help with.

Step-by-Step

Set the number of inputs into the Solution Search object. These inputs carry the data to be used in testing the Constraint rules, the number listed here is not the number of constraints.

Enter a Constraint Rule

Select the Add Button

Repeat for Each Rule to be Added.

Click on OK to set the Constraints.

Constraint Rules

There are 3 basic types of constraint tests <= (less than or equal) , = (equal) and >= (greater than or equal). Each rule consists of Left Side, a Test, and a Right Side.

The data coming into the Solution Search object is assigned to the variables a,b,c...z. So for example the rule a>=b means that input A must have a value greater than or equal to input B.

If input A is 10 and input B is 5, then the constraint is met because 10>=5.

But what is input A is an array {10,20,30,40} and b is an array {5,15,25,50}?

In this case corresponding elements would be tested and if all the tests are TRUE then the constraint is met. In this case all the constraints are not met,  40>=50 is FALSE and so the constraint test fails - the solution is not valid.

Objects Affected

Solution Search


The Number of Inputs into the Solution Search Object that will be used by the constraints rules. This does not specify the number of constraints. For example there could be 12 inputs and 30 constraint rules based on those 12 inputs.


Constraint Rule - This section defines a rule that will act as a constraint to the Solution Search object. When a constraint is tested, the inputs into the object A,B,C etc., are assigned to variables a,b,c... Each side of the constraint is evaluated and the two results compared using the test in the middle.

The sides of the constraint rule can be any function that evaluates, for example a*b >= sqrt(c) is a valid constraint with the left side a*b and the right side sqrt(c).

a = b
c+2 >= d
a >= 0
a>= {10,20}
a>={{10,20},{10,50,60}}

3=2 (this is always FALSE)
-1<=a*a (this is always TRUE)


Add - Adds the constraint entered in the Constraint Rule section to the list of constraints. You must enter a Left and Right side to the constraint before this button is enabled.


Change - Replaces the selected constraint from the list, with the new rule entered in the Constraint Rule section.


Delete - Deletes the selected constraint from the list.


This is a list of the constraints entered in the object, if a constraint has not been entered in this list, then it has not been set.


Solution Type

Introduction

The Solution Search object searches for an optimum result. This dialogue specifies what optimum means, either the maximum, minimum or nearest value to a particular result.

The Solution Search object is based on a Numerical branch of mathematics called optimisation. Hence it works only on Numeric Types, other types (such as dates) are converted to numeric types before use and this may lead to unusual results.

Find Minimum Result

The minimum numeric result available within the given contraints is found.

Find Maximum Result

The maximum value numeric result possible within the given constraints is found.

Find Nearest Match

Finds the number closest to the number entered in the edit field.

Nearest on this dialogue does not refer to the Vague Logic sense of Nearest. This option does not invoke a Vague Logic test.

Objects Affected

Solution Search


Outputs to Change Dialog
Outputs to Change

Introduction

The Solution Search object varies outputs in order to optimise the result of a calculation. The solution it finds is the output values it used that produced the optimum result. It starts off with an initial set of Start Values - this dialogue sets those values.

What is an Output?

There are up to 26 output pipes coming out from a Solution Search objects, labelled A to Z. Down each of these pipes are fed data of any type, even arrays of data objects.

The initial value you enter tells Solution Search the type of output object and how many parts there are to it. For example an output {1,2,3,4} tells Solution Search that this output is an array of 4 numbers and that these are treated as 4 unknowns.

If you specify non-numeric types, Solution Search will output an object of this type. For example an output 3+2i will cause a complex number to be output and this complex number will be treated as 2 unknowns by the Solution Search Object. This allows you to solve problems involving non-numeric types.

Any array required can be entered, for example if a column array output is required, enter the initial values as a column array {{1,2,3,4}} - notice the two sets of curly brackets indicating a column.

(Specifics).

Click on any part you need help with.

In the example dialogue shown, output A is an array with 3 values to vary, a number (initially 1.2), a date (initially \22nd Feb 92), and a time (initially 10:12:30). Output B has only a single number to vary with an initial value of 0.

Step-by-Step

Set the number of outputs, 26 outputs will still be included in the list, but only the number you specify will be used.

Select each output to be varied in the list one-by-one

Enter the start value in the Initial Output Value section.

Select the Change button to change the list entry

Select OK to exit.

Objects Affected

Solution Search


Specific Solver Output
Specific Actions for Solution Search Outputs

The following specifically lists how the Solution Search object handles different data types when outputting a result.

Integer Types	These are treated as 1 unknown. Because of their stop-start nature they may produce unreliable results. Outputs that include integers are always solved as non-linear problems.

Other Numeric Types	These are treated a 1 unknown and their value varied.

Null Object	Cannot be varied and can not be used as output values.

String Objects	Cannot be used as output values.

Equation Objects	Cannot be used as output values.

Boolean	Objects are varied to be TRUE or FALSE, but because of their disjointed behaviour, Boolean objects may produce unreliable results.

Time Objects	Are treated as 1 unknown - internally they are converted as the number of seconds since midnight.

Date Objects	Are treated as 1 unknown - internally they are converted to the number of days since 1st Jan 1900.

Complex Numbers	Are treated as 2 unknowns, internally they are split into 2 numeric values.


Number of Outputs - the number of output pipes that can be drawn off the object.

This is not the number of unknowns to vary because more than 1 unknown can come out of an output pipe.


Initial Output Value - Enter the initial value of the output in this edit field. This can be a simple number, for example 2.3, or an array of numbers {1,2,3} or other object types such as complex numbers {1+3i, 10+6i}.

It is not enough to enter it here, you must select Change to change the selected entry in the list.


This list shows the 26 possible outputs A to Z and their initial values. Notice that this always displays all 26, even if the number of outputs is less than 26.


Restore - If you have edited a Solver Output, then selecting this button will restore it to its original entry.


Change - Changes the selected output in the list, for the Initial Output Value you have entered.

To Change an Entry

Select it from the list, its value will appear in the Initial Output Value section.

Edit the Entry

Select the Change button to change, or Restore to discard the changes.


Solution Dialog
Solution

Introduction

When the Solution Search Object is in use, this dialogue displays its progress and allow you to interrupt it.

Click on any part you need help on.

In this example dialogue, reading top to bottom

A optimum result of 4424.89465 has been found

The values that achieved this were 10.8026131, 48.9617358, 0 and 20.683621

The Status shows that a solution was found using Linear Programming techniques.

The bottom section shows the value of the constraints at the solution, and that all of these constraints were met (there are no 'x' before any of the constraints).

Objects Affected

Solution Search


Result - the result to be optimised is displayed here.

Read the Status line before accepting this value, it may be that an optimum solution could not be found in which case this Result is meaningless.


Output Values - As different output values are tested, they are displayed in this section. Once a final result has been found, that optimum set of outputs is displayed here.


Status - Displays a message indicating the progress Solution Search is making. When Solution Search stops, this displays a message telling you if a valid solution was found.


Constraints - When Solution Search has finished, it displays a list of the constraints evaluated at the final solution.

An 'x' before the constraint indicates that the constraint was not met.


Stop - stops the Solution Search object from continuing. This cannot be used during the linear test phase, or during solving by linear programming.


Print - Prints a report of the solution, the outputs that generated that solution and the constraints at the solution.


This icon revolves to indicate the Solution Search is still running.


Sum Product Dialog
Sum Product

Introduction

The Sum Product object implements common calculations that involve the sum of a product (a product is the name given to the result of a multiplication). This dialogue controls how that object behaves.

There are 2 steps, the product is the first step in the calculation, the summation is the second.

Multiply the First Column of B by Each Column in A

Each element of array A is multiplied by the element from B that is in the same row of the first column. Any other columns in B are ignored.

In the above example the first row of A is multiplied by 3, the second row is multiplied by 5 and the third row by 3.

Multiply Corresponding Elements in A and B

Elements from A are multiplied by the element from B that is in the same row and column position.

If one array is bigger than the other, only where the two arrays overlap is calculated. For example if array A is 4 columns of 5 rows and array B is 5 columns of 4 rows, the interim result has 4 columns of 4 rows.

Multiply the First Row in B by each Row in A

Each element in A is multiplied by the element from the corresponding row of B.

Sum the Columns to Produce a Row Result

The result from the Product stage is summed down its columns to obtain a row of totals.

Sum the Rows to Produce a Column Result

The result from the product stage is summed along the rows to obtain a column of totals.

Objects Affected

Sum Product


Product Dialog
Product

Introduction

The product object calculates the product (product is the name given to the result of a multiplication) of two arrays. The Product dialogue controls how that object combines the arrays.

This usually operates on arrays, but it can also multiply an array by a single value.

Multiply by the item from the corresponding row in B

Each element in A is multiplied by the element from B that is in the same row of the first column. If there are several columns in B only the first column is looked at.

Multiply by the item from the corresponding column in B

Each element in A is multiplied by the element from B that is in the same column, but the first row. If there are several rows in B, only the first row is considered.

Multiply by the corresponding element from B

The elements of A are multiplied by the corresponding element (elements from the same row and column) of B.

If A and B are different sized arrays, then the result only covers where the two arrays overlap.

Multiply all items in A by item B

All the elements of A are multiplied by the single element B. If B is an array, then the first element in the array is used.

Objects Affected

Product


Cog Equations Dialog
Cog Equations

Introduction

The Cog Object is one of the most flexible objects within CleanSheet, if you think of the Calculator Object evaluating an equation, the Cog object evaluates many equations to form a resulting two dimensional array. Different equations cover different parts of the result array.

The Cog Object operates on parts of arrays to construct result arrays. It is the nearest thing in CleanSheet to the grid calculation style of a normal SpreadSheet.

Using the Dialogue

Click on any part you need help on.

The Cog Equations

The first decision to make with a Cog Object is How big an array am I trying to construct? This is set on the Cog Output Size dialogue.

The next step is to enter the equations into the list that assembles the array. For each equation you must first select the area of the result array that the equation applies to. This is done using the Set Area button which takes you to the Area Affected by Equation dialogue.

Then you must enter the equation, you can either type it in directly or use the Paste Function and Paste Input buttons to let CleanSheet help you.

For example, if the Result array is to be the sum of the corresponding elements of A and B where A and B are arrays:

Area affected by Equation	All

Equation	A[dx][dy]+B[dx][dy]

Notice that the Cog uses dx and dy to index into input A and B. A[dx][dy] is column dx, row dy of the two dimensional array A. As the Cog Object calculates different parts of the result, dx and dy are changed to get the corresponding parts of the inputs. If the equation were changed to A[dx][dy]+B[ 0 ][dy] then this equation would multiply the elements of the first column in B by the corresponding elements in A.

For a more complete explanation of the Cog Equations see Cog Calculation Object. For an example See How Cog Works.

Adding an Equation Step-by-Step

Select Set Area, to set the area affected by the equation.

Enter the equation directly or

Use Paste Function and Paste Input to help you

Click on Add to add it to the list

Objects Affected

Cog Calculation


Enter the equation that is to be added in this edit field.


Set Area - Sets the area affected by the equation. Each equation applies to a specific area of the result array. Selecting this button takes you to the Area Affected by Equation dialogue.


Paste Function - Pastes the name and parameters of a CleanSheet function into the equation. Selecting function names this way help to reduce the chances of making a mistake.

See the Paste Function Dialogue for more details.


Paste Input - Pastes an Input Area into the equation. It can be very difficult to understand that, for example, B[2][dx] refers to the elements of column number 2 from input pipe B, transposed into a row. This dialogue gives you a graphical way of specifying a section on any input.

See the Paste Input Area dialogue.


Add - adds the equation and affected area to the list of equations in this Cog object.


Delete - Deletes the highlighted equation from the list.


Change - Replaces the highlighted equation and area in the list, by the equation and affected area at the top of the dialogue.


Area - This line specifies the area of the result array that this equation applies to.

All	means that all of the result array

Column 1	means all of column 1

Row 2	means all of row 2

{1,2,5,6}	means Column 1, Row 2 to Column 5 Row 6

{1,2,edge,8}	means Column 1, Row 2 to the right edge of the result array, Row 8

When areas are given as {x1,y1,x2,y2} this refers to the left column, top row, right column, bottom row respectively.


The list of equations used by the Cog object is shown here. In this example there are two equations.

The first covers column 0 of the result and is A[dy][0] which is the first row of A.

The second equation covers column 1 of the result and is A[dy][1] which is the second row of A.

These equations together would produce a two column array that is the transposed first two rows of A. It could have equally been done with a single equation.


Area Affected by Equation Dialog
Area Affected by Equation

Introduction

A Cog object consists of a group of equations used to calculate a result array, different equations are used when producing different areas of the result.

Each equation has information stored with it indicating which part of the result array it should be used for. This dialogue sets that information.

Click on any part you need help with.

You can set the affected area by using the mouse on the right hand side of this dialogue.

Objects Affected

Cog Calculation


Left - the first column of the area affected. Columns in CleanSheet are numbered from 0,


Top - The first row of the area. Rows in CleanSheet are numbered beginning with 0.


Right - The right column of the area. The specified column is included in the area, e.g., Left 1 to Right 2, includes column 1 and column 2.


Bottom - The bottom row of the area. The specified row is included in the area, e.g. Top 1 to Bottom 2, includes row 1 and row 2.


Right Edge of Array - The area affected by the equation extends all the way across to the right edge of the result array.


Bottom Edge of Array - The area affected by the equation extends all the way down to the bottom edge of the result array.


Graphic Display - this section of the dialogue displays graphically the area you have selected. You can also change the selection using the mouse.

To Select an Area

Click with the mouse at the top left corner of the section.

Drag the mouse to the bottom right corner of the section.

Release the mouse button.

If you drag to the far right or far bottom of the Display area,
then this is taken to mean the Right Edge of the Array,
or the Bottom Edge of the Array.

To Select a Column

Double click in the centre of the column.

To Select a Row

Double click at the edge of a column.


Paste Input Area

Introduction

This dialogue is called from within the Cog Equations dialogue.

When defining an equation for a Cog object, it is necessary to define parts of input data to work on. For example an equation might include A[0][dy] which is the first column of input A.

But knowing that, to get the first column from input A, requires A[0][dy] is beyond most people and so this dialogue constructs phrases like this automatically and inserts them into your Cog Equation.

Before using this dialogue to construct phrases, you must already have set the area affected by the equation. This you do with the "Set Area" button on the Cog Equations dialogue.

Click on any part of the dialogue you need help with.

Constructing a Phrase

A Cog in CleanSheet is a Corresponding Objects Grid. This is important because all calculations are performed on corresponding parts of the input arrays.

If a Cog equation covers only a single cell of the result array, then it can only operate on single cells of the input arrays, or single sections of input arrays.

Similarly if the equation affects a column of the result array, then it can operate on columns or rows of the input arrays.

If an equation affects the whole of the result array, then it can use all the elements of the input arrays.

This is why it is necessary to set the area affected by an equation before creating phrases within it - the area the equation affects determines the phrases created.

For detailed examples of phrasing using this dialogue see Standard Phrasing.

Objects Affected

Cog Calculation


Standard Phrasing (In Cog Object)
Standard Phrasing

Introduction

This section explains what phrases mean within a Cog Object. A phrase is a way of referring to an input into the Cog object so that some part of it is extracted.

For example if a Cog object was to create an array 4x4, based on a single equation that covered all of the result array - and if the equation was the single phrase A[0][0], then the result of the Cog object would be a 4x4 array of copies of column 0, row 0 of input A.

If on the other hand the equation was A[dx][dy] +3, then the result array would be a 4x4 array containing the elements of A, but with 3 added to each of them. The phrase in this equation is the A[dx][dy] part.

Before studying phrasing, you should read How Cog Works.

Examples

If the area affected by the equation covers only a single element of the Result, then any input phrase can only refer to single elements. In this example, the phrase would be A[2][3], there is only 1 element so there is no dx or dy in the phrase. A[2][3] is column 2 row 3 of A.

If the Cog equation affects a whole row of the input, then the phrase can refer to a whole row as well, since it is possible to take the Corresponding elements from the two rows.

The resulting phrase is A[dx][3], as dx goes from 0 to 6, the corresponding column number dx, row 3 is taken from input A.

In other words A[0][3] corresponds to Result[0][1], A[1][3] correspond to Result[1][3] and so on.

If the Cog equation affects a row, then it is equally possible to construct a phrase based on an input column. Here the elements from column 2 of A are matched against the elements of Row 1 of the result.

The phrase that defines this is A[2][dx]. Notice dx, is indexing into the rows, whereas before it was indexing into the columns. Hence A[2][0] corresponds to Result[0][1] and A[2][1] corresponds to Result[1][1]....A[2][5] corresponds to Result[5][1]

When the area affected by an equation is more than one row high and more than one row wide, then one allowed corresponding input would be to have an area the same size. The phrase for this input area is A[dx+1][dy+3].

When the top left corner of the affected part of the result is being calculated dx=0 and dy=0, hence the corresponding element would be A[1][3] (column 1, row 3 of A).

When the bottom right corner of the affected part of  the result is being calculated dx=2 and dy=1, hence the corresponding element would be A[3][4] (column 3, row 4 of A).

Another way of generating corresponding elements is to have an area of the input that is the same size, but transposed.

The phrase for this is A[dy+1][dx+3]. Notice the order of the dy and dx - the phrase is identical to the previous phrase, but with dx and dy exchanged. This has the effect of transposing the input.

When the result is being calculated, first the top left corner of the section is evaluated, dx=0 and dy=0. Hence column 1, row 1 of the result corresponds to A[0+1][0+3], column 1, row 3 of A.

When the bottom right square if being calculated dx=2 and dy=1, which corresponds to A[1+1][2+3] which is column 2, row 5 of input A.

Advanced Phrasing

Standard phrasing consists of phrases that can be defined using the Paste Input Area dialogue. However the Cog object can do much more. For most people standard phrasing is more than enough, but power-users can read Advanced Phrasing Techniques.


Advanced Phrasing Techniques (Cog Object)
Advanced Phrasing Techniques

If you can understand how to construct phrases yourself, then you can do some extremely complex manipulations without much effort.

Examine closely how an equation is evaluated within a Cog object.

Consider how the equation covering the highlighted section is handled.

For each of the elements it affects, dx and dy are assigned the values shown. The equation is evaluated, the result is then placed in the correct place in the grid.

Notice that dx and dy always start at zero regardless of where the affected area starts.

Once you understand how simple the basis of a Cog object is, you can construct phrases of your own.

Example

Affected Area	All

Equation	A[dx #~ 1][dy]

Size of Result	Maximum Input Width, Maximum Input Height

This single equation makes a copy of input A, but exchanges pairs of columns in the input array. It does this by XORing the column number (dx) with 1, so when Cog is calculating column 0 of the result, it is getting data from 0 #~1  = column 1. Similarly when Cog is calculating column 1, it gets its data from 1 #~1 = 0, column 0.

Example

Affected Area	All

Equation	A[3-dx][3-dy]

Size of Result	4 columns, 4 rows

Imagine the same 4x4 array from the previous example. This time the result is a copy of the array with the rows in the reverse order and the columns in the reverse order.


Which Input - There can be up to 26 input pipes into a Cog Object A to Z. This selects which of these the phrase is to be based on.


Left - the left column of the area covered by the phrase. The first column is column 0.


Top - the first row of the area covered by the phrase. Rows within CleanSheet are numbered 0,1,..2.


Right - the rightmost column of the area covered by the phrase. The right column is included in the area.


Bottom - the bottom row of the area covered by the phrase. The bottom row is included in the area.


Right Edge of Input - The right edge extends over to the right edge of the input. This is useful when the input array is expected to vary in width.


Bottom Edge of Input - The bottom edge extends to the bottom edge of the input array.


Graphic Display - this section of the dialogue displays graphically the area you have selected. You can also change the selection using the mouse.

To Select an Area

Click with the mouse at the top left corner of the section.

Drag the mouse to the bottom right corner of the section.

Release the mouse button.

If you drag to the far right or far bottom of the Display area,
then this is taken to mean the Right Edge of the Array,
or the Bottom Edge of the Array.

To Select a Column

Double click in the centre of the column.

To Select a Row

Double click at the edge of a column.


How to Treat Selected Area

When you select an area on the Cog object, the cells of that area can be treated in several ways:

Row by Row, Column by Column

Each selected cell is matched up to the corresponding cell in the affected area of the result, rows are matched to rows and columns to columns.

For example, if the equation affects the whole of the result array and the whole of Input A is selected, when Cog calculates row 0, column 0 of the result, it refers to row 0 column 0 of Input A. When it calculates row 2, column 1 of the result, it refers to row 2 column 1 of Input A and so on.

Row by Column, Column by Row

Each select cell is matched up to a corresponding cell in the affected area of the result, but the area is first transposed. Now if the whole of the result is affected and the whole of input A is used, then when Cog calculates row 1, column 2 of the result, it refers to row 2, column 1 of input A.

Treat as a single object.

Only one cell can be selected with this option, the input is the value of that cell. For example, if you select column 1, row 1 from input A, A[1][1] is used regardless of which part of the result is being calculated.

Treat as an array of objects.

The selected area is extracted as an array, independent of the section of the result being calculated. For example, if a calculation in a Cog object requires the Mean of column 0 of Input A, you could use this option to construct the phrase needed to extract column 0, then use the Mean function to calculate its mean. The finished equation would be mean(extract{A,{0,0},{0,32000}}) .

Sum the Area to Produce a Single Summation

The cells in the selected area will be summed and the result of that summation is used as the phrase. This doesn't actually generate the result, rather it generates the commands necessary to extract the section and calculate its sum.


Example of Phrase

This section displays an example of the finished phrase that you have constructed.


Size of Output Array (Cog) Dialog
Size of Output Array

Introduction

The Cog Object produces a two dimensional array as a result - this dialogue specifies the size of that array.

Width of Output Result in Columns

This section deals with the number of columns in the result array.

Fixed Width	The width is a fixed number of columns wide, enter the number of columns in the corresponding edit field.

Maximum Input Width	The width of the output is as wide as the widest input. For example, if the input arrays are 2 columns and 3 columns wide, then the result array will be 3 columns wide.

Maximum Input Height	The width of the output array is the height of the highest input. This is used when the result involves transposing an input, if the inputs are 4 rows , 5 rows and 6 rows high, then the resulting array would be 6 columns wide.

Plus an Additional	This adds additional columns to the width. This applies whichever of the above options is chosen.

Height of Output Result in Rows

This section deals with the number of rows in the result array.

Fixed Height	The height is the fixed number of rows, entered in the edit field.

Maximum Input Height	The result array is as high as the highest of the input arrays. For example if the inputs have 2 rows and 3 rows, the result array would be 3 rows high.

Maximum Input Width	The result array has the same number of rows as the maximum number of columns in the input. If the inputs are 2 columns and 3 columns wide, the result array would be 3 rows high. This is useful when the result array is transposed from the input array.

Plus an Additional	This adds additional rows to the height. This option applies regardless of which height options are chosen.

Example

If you are using a Cog object to add column and row headings to an input array, then the options to choose would be:

Maximum Input Width

Plus an Additional 1 Column

and

Maximum Input Height

Plus an Additional 1 Row

If the input array was 2 columns by 3 rows, then the result array would be 3 columns of 4 rows, the extra row and column is for the headings.

Objects Affected

Cog Calculation


Button Group Style Dialog
Button Group Style

Introduction

This dialogue controls the style and output from a Button Group object. There is a companion dialogue - the Button Data dialogue that controls the actual values of each button.

Click on any part you need help with.

Objects Affected

Button Group


Radio Buttons

When a button is pushed in this group, the other buttons pop out. Only one button can be pressed at any one time. The value this group inputs into the sheet is the value of the single button that is pushed.

Example - the value from the following group is 4 (the values assigned to the buttons are the same as the text displayed on them in this example).


List of Buttons

Any number of buttons can be pushed down. The result from a List of Button is a 1 dimensional array with the value of each button represented in it. The buttons are listed in the order left to right and top to bottom.

Example: if all the buttons are set to have the value TRUE when selected and FALSE when not selected, then the following button group would input the array {TRUE, TRUE,FALSE,FALSE} into the sheet.


Grid of Buttons

Any number of buttons can be selected. The output from a Grid of Buttons is a 2 dimensional array (a Grid) of values according to whether the buttons are selected or not. The grid's width and height match the number of buttons across and down.

Example: if all the buttons are set to have the value TRUE when selected and FALSE when not selected, then the following Button Grid would input the array {{TRUE, FALSE},{TRUE,FALSE}} into the sheet.


How Many Buttons

This section defines how many buttons across and down the group there are. If the Group Type is a Grid of Buttons, then this also defines how many columns and rows are in the result.


Button Style

Selects from the various button styles available. A sample of each style if displayed in the Sample section of this dialogue.


Width Balancing

The width of the buttons varies according to the text on their face. Width balancing allows for a more even display of buttons.

Balance Columns

The width of each column is the width of the largest button in the column.

Balance All Buttons

The width of the columns is the width of the largest button in all of the columns. All buttons are the same size.


Button Data Dialog
Button Data

Introduction

The button data dialogue controls settings that are specific to each button in a button group. For example the buttons value, the text on its face and its keyboard equivalent.

Before using this dialogue, you should set how many buttons and their type and style using the Button Group Style dialogue.

Click on any part of the dialogue you need help with.

Step-by-Step

Select each button using the 'Button Number whose Data is Displayed' list one-by-one

Select a shortcut key that will be used for this button

Enter the text displayed when it is selected

Enter the Value when it is selected

Enter the text displayed when not selected

If the button group is a list or Grid of buttons, enter the value when the button isn't selected (In Radio button groups this value has no purpose).

Select OK

Objects Affected

Button Group


Button Number whose Data is Displayed - Select the button whose data you want to edit. Buttons are numbered 1,2,3.. etc. up to how ever many buttons are in the group. This number simply gives their position in the group, it has no other purpose.


Shortcut Key Letter - The shortcut keys are the keyboard equivalents for selecting a button. The letters correspond to the equivalent keyboard letter without shift or control pressed.

If several buttons have the same keyboard shortcut, then the keyboard will operate the first of them.


Legend When Selected - The text displayed on the button when the button is selected.


Value When Selected - The value input into the sheet when this button is pressed (selected). How this value is used depends on the Group Type on the Button Group Style dialogue.


Legend when Deselected - The text displayed on the button when the button is not selected.


Value when Deselected - the value the button has to the sheet when it is not selected. The exact usage for this value depends on the Group Type on the Button Group Style dialogue.

This value has no purpose in a group of Radio Buttons.


Slider Options

Introduction

A slider is an input device that dynamically inputs data into a sheet. This dialogue sets the style and range for a slider object.

Text Display

This controls the display of the sliders value. As the slider moves this legend changes to displays it value.

Off 	No Text is displayed

Shown Above	The text is shown above the slider

Shown Below	The text is shown underneath the slider

Show End Legend

The slider varies between two extreme values. Show End Legend displays those values at the ends of the slider.

Range

The range is the domain over which the slider varies. The range not only specifies the limits, but also the object type that the slider produces.

Left/Top Value	The value the slider has when it is at the top of its travel, or the left of its travel for a horizontal slider.

Right/Bottom Value	The value the slider has when it is at the bottom of its travel, or the right of its travel for a horizontal slider.

The value varies linearly across its length between these two values.

Examples

Left 0, Right 100 gives the slider the range 0 to 100 numeric.

Left \1st Jan 1993, Right 31st December 1993 gives the slider the range of any day during 1993.

Objects Affected

Slider


Pallette Window Dialog
Pallette Window

Introduction

The Pallette Window dialogue controls the display and style of the window containing the pallette of objects.

Off

The pallette is hidden. This Pallette Window dialogue is the only place that a hidden pallette can be reopened.

Horizontal Ribbon

The pallette is shown as a horizontal ribbon above the button bar. The width of the ribbon is determined by the width of the main window, the height is set on this dialogue.

Vertical Ribbon

The pallette is shown as ribbon down the left side of the main window. The height is determined by the height of the main window, the width is set on this dialogue.

Separate Window

The pallette is placed in a separate window whose width and height are set on this dialogue.

Width/Height in Icons

Determines the size of the pallette window in object icons. One or other of these option may be disabled according to the style of pallette.

See Also

Object Pallette


Sheet View Dialog
Sheet View

Introduction

The Sheet View dialogue control how the layers, frames and pipes of a sheet are displayed. Options set on the dialogue are specific to a particular sheet and are saved with that sheet.

If you only wish to hide the frame or pipes for a few objects, then this should be done using the Object Attributes dialogue.

Click on any part of the dialogue you need help with.


An example of the settings is shown in this section.


Depth of View

Each sheet consists of 100 layers, the normal way of viewing these layers is one-at-a-time. However you can get a depth of view, viewing the current layer and several of the ones below it to the specified depth.

Objects on levels below the current level cannot be edited, only viewed.


Hide Lower Pipes

This option only applies when several layers are viewed at once. When selected it hides the data pipes connected to objects on lower levels than the layer being viewed. Objects on the view layer are unaffected.

Pipes that start in one layer and end in another, are drawn on their lowest layer.


Hide All Pipes

None of the pipes on any of the layers of the sheet are drawn.


Hide Lower Frames

This option only applies when several layers are viewed at once. With this option selected the frames around objects on layers lower than the current view layer are hidden. Objects on the view layer are unaffected.


Hide All Frames

All the frames around all the objects on all the layers of the sheet are hidden.


Fade Lower Layers - Off

All the layers are drawn in full.


Gradual Fade

The layers underneath the current view layer are drawn faded. The deeper they are, the more faded they are. This is very useful when displaying several layers as it helps you to distinguish the current view layer objects from those underneath it.

This option considerably slows down drawing, don't select it if your machine is at the lower limit for running CleanSheet.


Even Fade

The layers below the current view layer are drawn with an even (heavy) fade. This option is useful when you wish to obtain a rough idea of the lower layers, without any great detail.

This option considerably slows down drawing, don't select it if your machine is at the lower limit for running CleanSheet.


Scale Dialog
Scale

Introduction

The scale dialogue sets the scaling at which the sheet is viewed. This setting is saved with the sheet and is specific to the sheet.

There may be several view windows onto the sheet, each window can have a different scale, so you may wish to have a window with a long view, and another at normal scale.

Editing the sheet works the same at any scale, you can still edit, move and resize objects - regardless of the scale.

You may wonder what such an option is doing on a SpreadSheet program  - on a normal SpreadSheet, there is no point in zooming out, since one piece of the sheet looks very much like another. However on CleanSheet, each object contains related data and so it is useful to zoom out and get an overall perspective on the sheet - you don't need to read the exact numbers, it is enough to see how everything fits together. Use this feature with this in mind.

The scale set here affects only the view on screen, the scale during printout is set on the Print dialogue.

50%	The sheet is drawn at half size (half height and half width)

100%	Full Size

200%	Twice normal size (twice the height and twice the width)

Scale to Fit 	The size is reduced so that all the object fits within the window (the minimum permissible scale is 5%, Scale to Fit will not reduce scaling below this).

Custom 	The scale is set in the edit field, it must be in the range 5% to 1000%


Pipe Options Dialog
Pipe Options

Introduction

The data pipes within Cleansheet represent data flowing from one object to another. They pipe the data around the sheet. On a traditional spreadsheet you don't see the data links, they're hidden in the formulae on the sheet, but by making these links visible, CleanSheet can highlight circular references, highlight error and give other visual cues.

This dialogue controls the behaviour of the data pipes.

Click on any part you need help with.


Horizontal and Vertical - The pipes only contain horizontal and vertical line segments.


Diagonals - The pipes contain diagonal line segments at 45 degrees.


Point to Point - The Pipes will join by a single straight line.


Colour by Content - There are 12 different data types that can be carried by a pipe. Each type gives the pipe a different colour.


Colour Recalculated Pipes - CleanSheet does not recalculate all pipes, every time, it uses a system called Sparse Recalculation to determine which pipes need calculating. You can monitor this happening by selecting Colour Recalculated Pipes. The pipes that are calculated become Green, the pipes that aren't calculated become grey.


Colour Errors Red - Pipes that contain error objects are coloured Red, other pipes are coloured grey.

A pipe may contain an array, which contains an error object without turning red.


Colour Circular References - Circular references are objects that are connected in loops. You may have planned these, in which case this option has no use to you. However if the loop exists by accident, then finding it can take a great deal of time. At this point you should use this option, it will colour circular reference pipes red and the remaining pipes grey.


The viaduct style cannot be used with the Point-to-Point line join style.


Information on the options selected is given in this section.


Calculation Options Dialog
Calculation Options

Introduction

This dialogue controls how CleanSheet proceeds when it encounters a circular reference within the sheet. A circular reference is a group of objects that are connected in a loop.

Don't Evaluate Circular References

With this option selected, CleanSheet will stop calculating and warn you of a circular reference. To find where it is, select Colour Circular References on the Pipe Options dialogue.

Evaluate Circular References

With this option, when a circular reference is encountered, CleanSheet keeps going. Since it is in a loop, it would go on forever unless one of the objects in the loop has been designed to stop it. Even so CleanSheet sets an upper limit on the number of times it will go around the loop.

Enter the maximum number of loops permitted in the Maximum Loops section.

This dialogue has nothing to do with the Solution Search object. Sheets that include Solution Search are connected in loops, but there is no need to alter the settings on this dialogue to use it. Solution Search will not cause a Circular Reference Error.


Title

Introduction

Objects Affected


Input Table Options

Introduction

The Input Table object has two option specific to it - how to move the selection point and whether to remove column and row headers. This dialogue controls those settings.

Insert Point Motion

When you enter text into a cell on an Input Table, and press Return  to accept the text, CleanSheet can automatically move the insert point to the next cell.

None	No movement occurs

Step Right	The insert point moves right one cell

Step Down	The insert point moves down one cell

Process Data

You may have row or column headings within your input table. These headings are usually not part of the data and so you may want them stripped off the data.

Strip First Column	Removes Column 0 from the input table before sending it out to the sheet.

Strip First Row	Removes Row 0 from the data before sending it out to the sheet.

In this example the first row and first columns have been stripped.

Objects Affected

Input Table


The Return key is sometimes called 'Enter' and sometimes labelled


XY Scatter Series Style Dialog
XY Scatter Series Style

Introduction

The XY Scatter graph draws data series as lines or as markers. This dialogue controls the style of that graph. It also controls the names of the series.

Step-by-Step

Select the series whose style is to be edited

Edit the name of the series

Set the marker style and colour

Set the Series line

Click on any part you need help with.

Objects Affected

XY Scatter Graph


Select which series is to be restyled from this list.


This edit field lets you change the name of the series.


Draw Marker at Point - if selected, this draws a marker at each of the points in the series.


Select the colour of the marker. A marker consists of 2 colours, the other is the Series Line colour.


The style of marker is selected from this list.


The Line Style for the line joining the points in a series.

Off - 	Line Hidden

Dashed

Dotted

Dash Dot

Dash Dot Dot

Solid


The colour of the line joining the series points. This also sets the contrast colour for the markers.


A sample of the series style is shown here.


XY Scatter Function Points

Introduction

An XY Scatter Calculation object has a curve drawn on it which represents a function. There are two main ways of drawing that curve.

If the curve exists as a table of data, then this dialogue is used. It allows you to enter the points of the curve by their value.

If the curve already exists graphically, then it could be scanned and pasted  into the background of  this graph, then traced by hand (see Empirical Functions). Even if this is done, you may find this dialogue useful for editing or correcting the data points.

Click on any part you need help with.

To Add a Point to the Curve

Enter the X of the point.

Enter the Y, the graph will be rescaled if necessary to fit the new point.

Click on Add.

The new point will be added into the list at the correct place - so that the X coordinates are sorted into ascending order.

To Change a Point on the Curve

The points on a curve are referenced by their X ordinate, if you need to change the X as well as the Y, delete the old point and add a new point.

Click on the point whose value you want to edit. Its X and Y will appear in the edit fields.

Edit the new Y, (you cannot change the X without delete the point first)

Click on Change.

The specified X value will have its Y changed to the new value.

To Delete a Point from the Curve

Click on the point to be deleted.

Click on delete

Objects Affected

XY Scatter Calculation


Enter the X value of the point to add in this field.


Enter or Edit the Y value in here.


The curve if displayed graphically in this section of the dialogue.

To select a point on the curve, click on it with the mouse.


Add - Adds the XY coordinate pair to the curve. The point is inserted in the correct place to keep the list sorted into ascending X order.


Change - Changes the point with ordinate X to the new value of Y. It is not possible to change the X value as well with this button, to do that you must delete the old point and add the new.


Delete - Deletes the point with ordinate X. You can click on a point to put its coordinate pair into the X and Y fields, then select Delete to delete it.


Clear All - deletes all the points on the curve.


Empirical Functions

Introduction

When a function exists as an equation it is very easy to simply type the equation in and use it. But when the function is defined by observed results, representing those functions within a sheet is much more difficult.

Traditional Approach

The traditional approach to this problem is to approximate the function points with a simple curve or straight line, which works very well if the underlying function is a straight line or simple curve.

You will find CleanSheet has the normal curve and line fitting functions for this, together with much more powerful polynomial curve fits.

If  you believe that the data represents a simple line or a curve that can be approximated by an exponential or polynomial line, then Curve fitting is appropriate. See Curve and Line Fitting.

Graph to Graphical Function

When the empirical function exists as a graph (either XY cartesian or Polar Graph), it may be easier to trace the graph through onto a graph calculation object (Either XY Scatter Calculation or Polar Calculation).

To do this you need to be able to scan the graph into the computer for tracing - an example of the procedure used is given in the topic Tracing an Empirical Function.

Table to Graphical Function

When the empirical function exists as a table of data points, it can still be used by a graph calculation object (Either XY Scatter Calculation or Polar Calculation). Both of the function graph types allow you to enter function points, point-by-point into the graph using the XY Scatter Points and Polar Points dialogues.


Tracing an Empirical Function

Step 1 -  Scan the Graph into your Computer

For this you will need a suitable piece of scanning hardware and software. This feature is not provided by CleanSheet, nor is the hardware to do it.

Once it is in your scanning package, copy the section with the graph to the clipboard.

Step 2 - Paste it into the Graph Object

To paste the graph in, you must be in Use Mode. Select the object by clicking on its frame.

When you select Paste, the graphic in the clipboard will be pasted into the background of the graph.

Step 3 - Position the Background

The background may not be large enough, or may be the wrong shape.

To resize the background, the Graph Paint Mode must be set to 'Move and Resize Components'.

To resize the background - click on it with the mouse (click outside the plot area) to select it and resize using the resize points that appear when it is selected.

Alternatively, select the Background menu option and select Stretch Horizontally and Stretch Vertically to adjust the size of the graph to the size of the background.

Step 4 - Size the Plot Area

Select the plot area and resize it to cover the section of the graph to be traced. The plot area is the section of the graph where the graph is plotted.

To resize the plot area, the Graph Paint Mode must be set to 'Move and Resize Components'.

This is a real example of an engineering curve being traced (it represents Bending Moments along the length of a Steel Roof Beam). To make it clearer a red rectangle has been drawn around the Plot Area.

Step 5 - Set the Scale

We must set the scale of the graph object to match the scale of the graph we are tracing.

For the X scaling, 10 steps of 0.2 will give us the correct range.

For the Y scaling,  7 steps of 0.1 will gives use the correct range. (The curve we want uses the scale on the left of the graph).

Step 6 - Trace the Graph

To trace data points, the Graph Paint Mode must be set to 'Paint Coordinate Data'. To Place a point simply click the mouse over the curve. Repeat this for the full length of the curve.

The curve we are tracing is the -MB curve, only 1 function can be represented on any graph object.

Step 7 - Examine the Result

Switch off the background, by selecting the Background dialogue and selecting solid colour.

You now have a graph you can directly use as a function.

A copy of this graph object is available in the example file EMP1.CLN, a copy of the original clipboard content is available in EMP1.CLP. You can open file this with the Windows Clipboard and try this tracing for yourself.


This is the background to the graph. It contains the scanned picture of the graph we are tracing.


The frame around the XY Scatter Calculation object.


The plot area of the graph must cover only the actual chart section of the graphic, not the axis text.


Pirouette Dialog
Pirouette

Introduction

Three dimensional graphs can only be represented on 2 dimensional displays, they cannot be drawn. The representation contains less information than the graph and this can lead to considerable confusion. In real life situations a person can judge a 3D scene by moving their head. Pirouette (a ballet dance spin), spins the graph continuously around its axes - this movement helps you to judge the 3D scene.

Step-by-Step

Set the rotation around each of the 3 axes.

Select Start to start the spin.

When you have finished watching the graph(s) spin, select Stop.

Click on any part you need help with.

Objects Affected

3D Graph


The amount to rotate the graph about the X axis in degrees.


The amount to rotate the graph about the Y axis in degrees.


The amount to rotate the graph about the Z axis in degrees.


Decrease the X axis spin by 5 degrees.


Increase the X axis spin by 5 degrees.


Decreases the Y axis spin by 5 degrees.


Increases the Y axis spin by 5 degrees.


Decreases the Z axis spin by 5 degrees.


Increases the Z axis spin by 5 degrees.


This button Starts and Stops the Pirouette.


This button closes the dialogue and stops the Pirouette if it is running.


3D Graph View

Introduction

This dialogue sets the view angle, perspective and stretch of a 3 Dimensional Graph object.

Click on any part you need help with.

Objects Affected

3D Graph


A sample of the view that the dialogue settings would produce is shown here.


This button decreases the rotation about the X axis by 5 degrees.


This button increases the rotation about the X axis by 5 degrees.


Decreases the rotation about the Y axis by 5 degrees.


Increases the rotation about the Y axis by 5 degrees.


Decreases the rotation about the Z axis by 5 degrees.


Increases the rotation about the Z axis by 5 degrees.


This shows the angle of rotation about the X axis in degrees.


This shows the angle of rotation about the Y axis in degrees.


This shows the angle of rotation about the Z axis in degrees.


The graph is based an on an imaginary grid of cubes, each with sides of length 100. By changing the height or depth of these cubes, you can change the relative height or depth of the graph.

Smaller height values will create short-squat graphs, smaller Z values will create graphs will little depth.

Conversely larger height values will create tall, slender graphs and larger Z values will create deep graphs.


This button increases perspective distortions. This makes a graph look more real, but also makes it more misleading.

For details see Perspective Problems.


This button decreases perspective distortions.


This field contains the perspective depth. A bigger number is a more parallel projection and hence less perspective distortion.

The maximum value is 10000, which is effectively a parallel projection.


Perspective Problems

Perspective on 3 dimensional graphs adds a great deal of realism. The problem is that perspective forshortening also adds a great deal of distortion which can mislead.

Consider the following two examples.

These are the same values, plotted on the same style of graph. The only difference is the amount of perspective distortion. Examine the second column, on the top graph is looks like it has a value of 70. Now examine the bottom graph, it appears to be over 80.

Getting Around the Problem

The problem is a fundamental one - 3 dimensional scenes do not lend themselves easily to 2 dimensional displays. There are however a number of thing you can do.

Set the perspective to 10000 (its maximum) and use the rotation. You can achieve nearly 3d effects by doing this without resorting to full perspective.

Pirouette the Graph. Viewed from different angles the perspective distortion becomes apparent.

Ignore the problem. The truth is that most 3d graphs are for presentation rather than data. With a middling level of perspective (say 500), the distortions are less important than the extra depth that perspective adds.


3D Axis and Grid Dialog
3D Axis and Grid

Introduction

The 3D axis and grid dialogue controls the style of the back, side and base faces that enclose a 3 dimensional graph.

Consider this dialogue step-by-step.

Step 1 - Set the Base Style

This section of the dialogue controls the base, there must always be a base.

Step 2 - Set the Left Face Style

This section of the dialogue controls the vertical face along the left side of the graph.

Step 3 - Set the Right Face Style

This section of the dialogue controls the vertical face that runs long the right side of the graph.

Step 4 - Set the Back Face Style

This section of the dialogue controls the style of the backface.

Step 5 - Set  the General Settings

If the faces are set to zero thickness, then they are only drawn when facing forward. This is useful when Pirouette is used to spin the graph, with zero thickness faces, the back faces do not conceal the graph.

Objects Affected

3D Graph


The 4 styles of base, the lines correspond to the line on the base.


This button is the colour of the base, select it to change that faces colours.


Front Edge X axis Text Labels.

The direction of the arrows indicates the line along which the text is drawn.


Left Edge Z Axis Text Labels

The arrows indicate the direction along which the text is drawn.


Right Edge Z Axis Text Labels

The arrows indicate the direction that the text is drawn.


These buttons control the lines drawn on the left face. The blank tile switches off the face.


The colour of the left face, this can be changed by selecting it as you would select a button.


Left Face Y Axis Text Labels

The arrows indicate the direction along which the text is drawn.


These buttons control the lines drawn on the right face. The blank tile switch off this face.


This button sets the colour of the right face.


Right Face Y Axis Text Labels.

The direction of the arrows indicates the direction of the text.


These buttons control the lines on the back face (the face behind the graphs). The blank tile switches off this face.


This button sets the colour of the back face.


Back Left Edge Y Axis Text Labels

The direction of the arrows indicates the direction of the text.


Back Right Edge Y Axis Text Labels

The direction of the arrows indicates the direction of text.


Font  - The Typeface Name, Style and Size used to display the axis text.


Axis Text Standoff - The size of the gap between the edge of a face and the text. The size is specified as a percentage of the width of the X axis intervals.


Thickness of Faces - The thickness of the faces that form the axis. The size is specified as a percentage of the width of X axis intervals.


3D General Settings Dialog
3D General Settings

Introduction

This dialogue controls the overall style for a 3 Dimensional Graph. For the options that are specific to each data series plotted see the 3D Series Dialog.

Click on any part you need help with.

Objects Affected

3D Graph


Interval Names

This section allows you to edit the names given to each interval.

In the example below the interval names are 'Jan' 'Feb' and 'March'.

Do not confuse the interval names with the series names (in this example 'Series A' and 'Series B'). Series names are set on the 3D Series dialogue.

Interval Names from Input Pipes

 Interval Names Input.

When the Interval Names input is connected, CleanSheet will get the names from that input pipe.

 Full Input point.

When the data comes in through the full Input point (top left corner of the frame) then CleanSheet will examine it for interval names. If one column or row of the data obviously represents interval names, CleanSheet will extract those names and use them.


Stack the Series

Series of the same type are stacked onto each other. For example column graphs will be stacked onto columns, ribbons onto ribbons and so on.


Separate Series

The series are drawn separately (not stacked), each series is drawn behind the preceding series.


% Spacing of X axis Columns

The percentage of width of a column given over to spacing column graphs. e.g. 20% means a fifth of the width is space between columns and four fifths of the width is columns.

This only affects column graphs, it has not effect on ribbon, area or other series styles.


%Spacing of Z axis Columns

The percentage of depth of columns given over to spacing between two series. e.g. 20% means that a fifth of the column depth is space, and four fifths is column.

This setting affects all series styles except the Sphere style.


3D Series Options Dialog
3D Series Options

Introduction

The style of each series on the 3 dimensional graph is set with this dialogue.

Click on any part you need help with.

Objects Affected

3D Graph


Series Names

The name given to each of the individual data series.

To change the name of a series:

Select it from the list

Edit its name in the edit field


A representation of the series style is shown here.


Spheres

The points of the series are drawn as spheres on the graph, the centre of the sphere is the plotted point. The diameter of the spheres is specified as a percentage of the width of the intervals.


Ribbon

The points of the series are drawn, joined by a ribbon. The ribbon extends downwards from the plot line. The thickness of the ribbon is set as a percentage of the width of the intervals.


Column

The points of the graph are drawn as vertical columns.


Area

The points of the graph are drawn as a ridge. The thickness of the ridge is set as a percentage of the width of the intervals.


The colour of the series is set with this button.


Advisor

Introduction

The Advisor analyses your problem and suggests an object that fits the problem. It does this by asking multi-choice questions. The answer you give suggests which objects are appropriate and which objects are inappropriate. As it grows more confident about particular objects, the questions it asks relate more and more to those objects.

If you already know the object you want to use, you do not need the advisor - you need the Help topic on the Object Palette.

The Object Icons

At the top of the dialogue are all the icons for all the objects. You can double click on any icon at any time to obtain help on it.

These icons start out greyed, as Advisor becomes more confident about an object, its icon becomes more solid, as Advisor rules out objects, their icons become more greyed.

Restart

When you wish to start a new Advice session, select Restart to initialise the Advisor.

Rethink

If, and only if, you think that the Advisor is completely on the wrong track, then select rethink. This button should only be used if the object Advisor suggests has absolutely nothing to do your problem. Selecting this button causes Advisor to go off at a tangent, if it is selected unnecessarily, then you will keep wandering around the Advice topics without aiming at anything.

Step-By-Step

Click on Restart to initialise the Advisor.

Read each statement and select the best answer to the question.

When Advisor thinks it can focus in on a single object, it will highlight that object and tell you about it.

When it has found an object you want, select the answer that will provide you with the Help for it.

You may continue if the object is unsuitable, Restart to try again, or Close the Dialogue.


Printer Setup Dialogue
Printer Setup

Introduction

This dialogue selects the printer which is the destination for all printing in CleanSheet, it also sets options specific to each individual printer.

The list of available printers is shown on the dialogue, to change printers, simply select one from the list and click on OK.

To set options specific to a particular printer, select the printer from the list and select the 'Set Up' button.

Selecting a Printer on this dialogue, sets that printer as the default for all the applications you are running.

If you want to add additional printers to the available list, Select Printers in the Windows Control Panel.


Input Table Object
 Input Table

Introduction

The Input Table inputs two dimensional data arrays into a sheet. The arrays (see CleanSheet Data types) can contain any object, or combination of objects.

The input table is not recalculated live, data you enter into this object is calculated once to obtain a constant and these constants are placed in the table. The Input Table is not treated as a spreadsheet, each element in the table is independent of every other element, and no element can be derived from another element.

It is important that each Input Table contain related data. You may be tempted to place all you data into a single Input Table and then attempt to manipulate parts of it, but this will only add needless steps to a calculation. If two pieces of data are unrelated, then they should be in different input objects.

Frame Style

Along the right edge are outlets for the sum of the rows, along the bottom are the outlets for the sums of the columns and in the bottom right corner is the outlet for the complete array. The summation outlets are to speed up the most common calculation done by a sheet.

For Example

Notice in this example the top row is headings. To stop headings being included in a calculation, select 'Strip First Row' on the Input Table Options dialogue.

Entering Data into the Table

To enter data into an input table, you must be in Use Mode.

Use the cursor keys or mouse to position the Insert Point (shown as a thick rectangle) over the cell to be edited.

Click with the mouse in the edit field at the top of the CleanSheet window.

Alternatively, simply type at the keyboard.

Enter a CleanSheet data object or expression (See Entering Data).

Press Return, or select the tick.

Selecting Areas

To select part of the table, the Sheet must be in Use Mode.

Selecting a Rectangle	Drag the Mouse over the rectangle. If the Shift key is held down, any previously selected region will be extended. You can also select an area with the keyboard. Hold down Shift and use the cursor keys.

Selecting a Column	Double click in the centre of a column (See Illustration 1).

Selecting a Row	Double click at the edges of a column (See Illustration 2).

Selecting the Whole Grid	In any corner cell - double click in the centre to select the column. Hold down the Shift key and double click at the edge of the column to extend the selection across all the rows.

Clipboard Usage

To perform any clipboard operation on the contents of the Input Table, you must be in Use Mode.

Clear	Deletes the selected area of the Input Table. The contents of the cells that were selected are removed. Note: the table stays the same size, only its contents change.

Copy	Copies the contents of the selected cells to the Clipboard.

Cut	Copies the selected cells to the Clipboard and deletes the contents of the cells.

Paste	Pastes the cells in the Clipboard into cells in the input table, starting at the Insert Point and extending right and down. If the Input Table is not large enough, the pasted data is cropped.

Keyboard controls

Keyboard controls only take effect when in Use Mode.

 	Moves the insert point to the top of the column.

 	Moves the insert point to the bottom of the column.

Up one row

Down one row

Left one column

Right one column

 	Left 5 Columns

 	Right 5 Columns

Up 5 rows

Down 5 rows

Resizing the Cells of a Table

There are two ways to resize the cells of a table. Firstly using the Grid Style Dialog in Edit Mode, this dialogue asks you for the width and height of the grid elements. Secondly, when in Edit Mode, you can use the mouse to resize the columns.

Move the mouse over the grid lines

The mouse cursor will change shape

Click and Drag to move the boundary line

If you hold down the Control key while moving the line, all the columns will be resized.

Prototyping

When an Input Table is first dropped onto a sheet, the format for displaying numbers, dates, time objects and complex numbers is undefined. The first one of each of these data items you type in is analysed and a suitable display format is selected by CleanSheet. That format is then used for all the remaining data you enter into that Input Table.

Example, if the first number you enter is £1.25, then you enter a second number 4.50, the second number will be displayed as £4.50.

Not all formats will be invoked, CleanSheet will select formats that produce reasonable result for most numbers. For example, entering 22 as your first number will not set the format to an integer format simply because there was no decimal point in the number.

Usage Example

The file Linear.cln contains some typical examples of an Input Table.

Dialogues supported

The dialogs that set the style of the elements, either operate on the whole of the table if there is no selected area, or on the selected part of the table if there is one.

 Font Selection	Selects the typeface style, colour and size

 Colour Selection	Select the fill colour of the cells

 Negative Numbers	Determines if negative numbers are to be highlighted

 Number Format	Controls how numbers are displayed

 Date Format	Controls how dates are displayed

 Time Format	Controls how times are displayed

 Complex Format	Controls how complex numbers are displayed

 Alignment	Controls alignment of text in each cell

 Number of Row/Cols	Sets the number of rows/columns in a grid

 Input Table Options	Sets options specific to the Input Table

 Grid Style	Sets the style and spacing of the grid

 Object Attributes	Sets the object's tags and name

 Border	Sets a border around a group of cells

 Fill Up/Down	Extrapolates the contents of selected columns

 Fill Left/Right	Extrapolates the contents of selected rows

 Sort	Sorts the Input Table

 Search	Searches through the Input Table

 Import Data	Imports data from a file.


This column of headings is not included in the calculation.


100+201+10.34 = 311.34


120+202+15.84 = 337.84


100+120 = 220


201+202=403


10.34+15.84 = 26.18


The output from this outlet is an array of 2 columns by 3 rows, since the option to Strip the First Row is selected, this array does not include the column headings.


Entering Data (Into an Object)
Entering Data

Data is entered using CleanSheets object notation. This notation tells CleanSheet what data type you are entering.

Numbers	Type the Number in as you would read it. e.g., 3.245 is a (double precision) number.

Integers	Type the Number followed by an '@' symbol, e.g. 3@ is the integer 3.

Strings	Type the String of characters enclosed in double quotes, e.g., "A String of Text"

Dates	Enter the date preceded with a backslash, e.g., \20th Feb 1992 is a date object. CleanSheet will always attempt to understand a date regardless of the style. e.g., \20/2/92 would equally have done.

Times	Enter the time object with colons separating the hours, minutes and seconds. There must be no spaces inside the time object. For example 10:12:14 is a time object. If the seconds are omitted then they are assumed to be zero. The AM/PM indication can be added to make the time a 12 hour clock reference, e.g. 10:12pm is equivalent to 22:12:00.

Boolean	Enter TRUE or FALSE

Null Objects	Enter NULL

Complex Numbers	A complex number is a real number with an imaginary part added. Enter the imaginary part by following it immediately with an i or j (j is used in engineering), for example 2i + 5 is a complex number with real part 5 and imaginary part 2, so is 5+2j.

Arrays	An array is a group of other objects. Array notation uses curly brackets { } to group object together, any object, even other arrays. Each element is separated from the rest by a comma.

One Dimensional Arrays

A 1 dimensional array is a simple group using the curly brackets, for example, { 1, 2, 3, 4 } is an array of 4 numbers.

These arrays are always shown as a single row.

Two Dimensional Arrays

A 2 dimensional array is a row array of column arrays.

Would be represented in array notation as {{1,5},{2,6},{3,7},{4,8}}

Notice that it is a row of 4 columns, each column has 2 elements.

N Dimensional Arrays

Traditional Spreadsheets use 2 dimensional data, because the grid used to enter data is 2 dimensional. CleanSheet concentrates on 2 dimensional data as well, since it is a familiar level to work with and to this end it has objects like the Input Table that create 2 dimensional arrays.

However using this system you are not restricted to 2 dimensional data, you can enter data with up to 10 dimensions, however that would be well beyond any persons requirements.

Example: {{1,{1,2}},{2,{6,3}},{3,{7,1}},{4,{8,8}}} is the same table we had above, but the elements of the bottom row are all 3 dimensional. This is impossible to represent as a grid without using array notation.

Entering Expressions

So far we have only covered entering simple objects, but wherever CleanSheet expects an object, an expression using any of CleanSheets functions will do. (For a list of functions and operators, see General Operators).

Example, if you entered Today-7, this would enter the date of the same day last week. Today is the function returning the current date and subtracting 7, gives us the date for a week ago.

When you enter a Complex Number, you are actually adding a real number to an imaginary part. 2+3i is a sum.


The tick on the button bar tells CleanSheet that you accept the data you have entered in the edit field.


This dialogue is only available in Use Mode.


This dialogue is only available in Edit Mode.


This dialogue is available in both Use and Edit Modes.


Tumbler Input Object
 Tumbler

Introduction

The Tumbler object is an input object for dynamic input. It has several natural properties:

There is no lower or upper limit, the Tumbler can turn around and around however many times are necessary.

There is a natural centre point which can be reached by clicking in the centre with the mouse

There is a visual feedback displaying its value.

By considering these properties you can decide when a Tumbler object is appropriate. If for example you need a lower and upper limit, then a Slider Input object may be more appropriate.

Frame Style

The frame has 4 outlets, to allow pipes to be taken off in 4 directions.

Any number of pipes can be taken off the Tumber frame, all of these pipes will be assigned the same value by the tumbler object.

Tumbler Equation

The Tumbler object contains an equation that links the angle it is set at, to the value it produces. This is a regular CleanSheet expression and hence can produce any data object of any data type. The expression is a function of x where x is the angle in degrees, zero is taken as upwards and the angle increases when turning the Tumbler clockwise.

To edit the equation:

Switch to Edit Mode

Double click on the Tumbler Object

Edit the equation in the edit field at the top of the main window

Press Return or click on the Tick.

Example, the expression x/360*365+ \1st Jan 1993 would produce date objects where each rotation corresponds to 1 year. The central value of the Tumbler (when x=0) would be \1st Jan 1993.

Setting the Tumbler with the Mouse

To change the value of a Tumbler you must be in Use Mode.

Resizing the Tumbler

Switch to Edit Mode

Move the mouse over the tumbler object, as you move over the dial the cursor will change shape.

Click and drag out the resize box until it covers the size you want

Keyboard controls

To set the Tumbler using the keyboard, the sheet must be in Use Mode and the Tumbler must be selected (Tab until it is selected).

Reduce angle by 1 degree

Increase angle by 1 degree

Decrease angle by 10 degrees

Increase angle by 10 degrees

Zero the angle

Reduce angle by 90 degrees

Increase angle by 90 degrees

Usage Example

The file Xyscat.cln contains examples of the Tumbler object.

Dialogues supported

 Font Selection	Selects the typeface style, colour and size

 Number Format	Controls how numbers are displayed

 Date Format	Controls how dates are displayed

 Time Format	Controls how times are displayed

 Complex Format	Controls how complex numbers are displayed

 Tumbler Options	Sets options specific to the Tumbler

 Object Attributes	Sets the object's tags and name


Summation Object
 Summation

Introduction

The summation object adds every part of every input fed into it to obtain a total. The only exception is string objects, these tend to be used as titles and adding data objects to strings is of minimal use, so strings are excluded.

Every section of the input is considered, this means that if one of the inputs is an array, all the elements of that array are added into the total.

This make the object suitable for summation of tables as well as totalising several inputs.

Frame Style

The frame has four inlets and four outlets, but they are all treated equally.

Any number of pipes can be connected to any inlet. Similarly any number of output pipes can be connected to the outlets, they will all receive the same result - the total.

Usage Example

In this example a table of numbers and strings is fed into a summation object twice (notice the same table is piped into two of the summation objects inlets). The summation object adds the contents of the object together excluding the strings ("Quarter 1" etc.) to obtain 1012.5+1023.4+2166.9+232.3 + 1012.5+1023.4+2166.9+232.3 = 8870.2

The result of this is a double precision number, but it may have been another data type, if the result of summation defined it.

Here the Summation object is adding a date object to a number. The rules of summation mean that the result is a date with the number of days added to it. In this case 15th August 1993 is 471 days more than 1st May 1992.

Dialogues supported

 Object Attributes	Sets the object's tags and name

Special Notes

It is not necessary to use a minimum of three objects simply to add a few numbers together. The examples used to illustrate the Summation object were overkill, it is not essential to use the Summation object in either of those examples.

If all you want is to simply add constant numbers together, use an Input Table Object and enter the sum into one of its boxes. The result will be calculated immediately and the displayed in the Input Table Object.

If you want the sum of a column or row from an Input Table, again simply use the summation outlets on the Input Table itself. This will be recalculated when the table is changed.


This is an Input Table Object, used to input an array of strings and numbers into the sheet.


This is the Summation Object, it adds all the data objects fed into it together to obtain a single total.


This is an Output Table, used to display the result onto the screen.


This is an Object Input Box, it inputs single data items into a sheet. In this case it is putting the number 471 into the Summation Object.


This is an Object Input Box, that is sending the date \1st May 1992 into the Summation Object.


This is an Output Table, displaying the result of the summation.


The Summation object is adding the date and the number together.


Output Table Object
 Output Table

Introduction

The output table displays CleanSheet data objects onto the screen. When the data being displayed is an array, this object can expand the first two dimensions to display it as a table.

This object is the main text output object, when you need to display data items to the user of the sheet, this is the object to use.

Frame Style

There are 4 inlets on the frame, but only one can be connected at any one time  - since only 1 data item can be displayed at any one time.

Notice that if the table is resized, any pipes connected to the inlets will be adjusted. It can be very frustrating to lay a pipe exactly how as want it, then resize the Output Table only to find your pipes have been moved. You should always set the Output Table objects exactly as you want them, then arrange the pipes.

Selecting Areas

To select part of the table, the Sheet must be in Use Mode.

Selecting a Rectangle	Drag the Mouse over the rectangle. If the Shift key is held down, any previously selected region will be extended. You can also select an area with the keyboard. Hold down Shift and use the cursor keys.

Selecting a Column	Double click in the centre of a column (See Illustration 1).

Selecting a Row	Double click at the edges of a column (See Illustration 2).

Selecting the Whole Grid	In any corner cell - double click in the centre to select the column. Hold down the Shift key and double click at the edge of the column to extend the selection across all the rows.

Clipboard Usage

The only clipboard operation supported by this object (and all output objects) is Copy, which copies the selected area to the clipboard. To use Copy you must be in Use Mode.

Keyboard controls

Keyboard controls only take effect when in Use Mode.

 	Moves the insert point to the top of the column.

 	Moves the insert point to the bottom of the column.

Up one row

Down one row

Left one column

Right one column

 	Left 5 Columns

 	Right 5 Columns

Up 5 rows

Down 5 rows

Resizing the Cells of a Table

There are two ways to resize the cells of a table. Firstly using the Grid Style Dialog in Edit Mode, this dialogue asks you for the width and height of the grid elements. Secondly, when in Edit Mode, you can use the mouse to resize the columns.

Move the mouse over the grid lines

The mouse cursor will change shape

Click and Drag to move the boundary line

If you hold down the Control key while moving the line, all the columns will be resized.

The <###> Error

When there is insufficient space to display a number or object, an error marker is shown instead. You may think this is odd, but consider an example where the number to display is 100000 and there is only enough room to display 5 digits. The user would see a figure 10 times too small. When it is not possible to display the output value, Output Table will not try to display a partial result.

When you see the error marker, switch to Edit mode, and resize the column and or row. You can also switch on the Wrap option of the Alignment dialogue, which allows the text to be wrapped around in its cell.

Usage Example

If you consider the following very simple example where the Output Table displays the array fed into it from an input object.

Dialogues supported

 Font Selection	Selects the typeface style, colour and size

 Colour Selection	Select the fill colour of the cells

 Negative Numbers	Determines if negative numbers are to be highlighted

 Number Format	Controls how numbers are displayed

 Date Format	Controls how dates are displayed

 Time Format	Controls how times are displayed

 Complex Format	Controls how complex numbers are displayed

 Alignment	Controls alignment of text in each cell

 Number of Row/Cols	Sets the number of rows/columns in a grid

 Grid Style	Sets the style and spacing of the grid

 Object Attributes	Sets the object's tags and name

 Output Table Options	Sets Redimensioning and Display style

 Export Data	Exports Data to a File

Special Notes

This table has an option to resize (redimension) automatically, this resizing means changing the number of rows and columns, not changing the widths or heights of individual rows and columns. Without this option the Output Table is restricted in the size of table it can display - any table you attempt to display that is larger, will be cropped at the right and bottom edge.

Redimensioning is a complex task, involving remapping of connecting pipes and a lot of moving of data. If you don't need this option, size the table correctly and switch the option off.

Redimensioning is set by the Output Table Options dialogue.

Areas of the table that contain nothing are greyed out.


This is a Object Input Box, this inputs arrays into a sheet using array notation.


This is the Output Table object, this object is set to display the result as a table, rather than using the array notation - notice that where there isn't any data to display, it draws the cell in grey.


Line/Column/Area Graph Object
 Line/Column/Area Graph

Introduction

The Line/Column/Area graph displays series of data within vertical intervals. There are several things that are important about this graph:

It is scaled in only 1 direction (up), if your data consists of coordinates on an XY graph, you should use the XY Scatter Graph.

Several graphs can be overlaid onto each other

Graphs can be stacked vertically

Graphs can be displayed as a percentage of the total

Frame Style

There can be up to 8 series overlaid on this graph object, each series can be piped in separately, or alternatively a two dimensional array can be put into the 'Full' inlet, this two dimensional array is broken down into separate series.

The interval names inlet is to input the names given to the horizontal intervals on the graph.

Individual Series Inlets

The inputs data for these is the data for one series only, the inlet you attach it to determines which series the data is for  - attached to inlet A and that is the data for Series A.

This graph object expects a 1 dimensional array of data into these inlets, however it can process two dimensional arrays to achieve the result it expects.

Full Inlet

The full inlet is used when all the series are in a single two dimensional array. This array can contains interval headings, titles and so on - the graph object analyses the array and decides what is what.

When a title is identified it is used for the appropriate headings.

If the titles are not being used correctly, if may be that the 'Get Names from Input' option is set (see General Options), if it is, then CleanSheet will expect to get names from the 'Interval Names' inlet.

You cannot mix Series Inlets with the Full Inlet, one or the other can be connected, CleanSheet will not allow you to connect both.

The Components of the Graph

The graph consists of many separate parts, the main part is the plot area, this section is where the data series are drawn. The index box shows a key linking the series to its name, the Title Box displays the title of the whole graph.

That leaves the background. For this graph object, the background is purely decorative and so it occupies the whole of the background to the graph and cannot be resized separately. Notice that the intervals labeled 'C' on the graph are the same size. The background adds the same amount of gap above and below the plot area in order to make the graph look nice. This means that if you want a larger gap below the plot area, you must move the plot area down.

The Title Box and Index Box are set using the General Options dialogue.

Resizing the Components

Switch to Use Mode.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The background and frame will be resized automatically

Clipboard Usage

When the sheet is in Use Mode, the graph can be copied as a picture to the clipboard and a Picture can be pasted in for use as the background, fill styles or markers.

Usage Example

The examples Graph1.cln and Graph2.cln contain samples of this object.

Dialogues supported

 Number Format	Controls how numbers are displayed

 Object Attributes	Sets the object's tags and name

 Grid Style	Sets the style and spacing of the grid

 Axis and Grid	Sets the style of the grid and axes

 Background	Sets the style of the background

 Series Options	Sets the style of each series

 Scaling	Set the scaling

 General Options	Set option covering all of the graph

Special Notes

There is a complementary object called the Bar/Line/Area Graph object which has exactly the same features as this object, but is a horizontal graph.

The graph can display pictures pasted into Area series. Windows has a limitation that may cause large graphs to be drawn incorrectly during printing if you use this option. If this happens reduce the size of the graph until the picture is drawn correctly.

Comparison with Traditional Spreadsheets

This object covers a whole range of percentage, stacked and overlaid graphs that are normally listed separately for marketing reasons.

For stacked graphs, select 'Stack onto Similar Objects' which will stack the selected graph style onto graphs that are the same style. This is selected on the Series Options dialogue and must be selected for each of the data series that will be stacked.

For percentage graphs, select 'Percentage Scaling' on the Scaling dialogue.

For logarithmic graphs, select 'Logarithmic' on the Scaling dialogue.


Banding Boxes

The banding box is for resizing a component of a graph. When it is displayed, the 6 resize points allow you to resize the component in the directions indicated by the arrows.

To move the selected item, drag the centre of the banding box to its new position.


Density Graph Output Object
 Density Graph (Output)

Introduction

The Density graph is a statistical area mapping chart. Put simply is maps values onto a grid, each value is displayed by varying the size of a spot, or by changing the colour of the square.

The density graph is used to relate numbers to geography and for this reason it usually has a map pasted into its background.

Frame Style

There are 4 inlets on the frame, but only one can be connected at any one time  - since only 1 data array can be displayed at any one time on this chart.

Notice that if the graph is resized, any pipes connected to the inlets will be adjusted.

The Components of the Graph

The graph consists of four separate parts, the main part is the plot grid, this section is where the density data is drawn. The index box shows a key, which details the density map style, the Title Box displays the title of the whole graph and finally the background is drawn behind the other components.

The background on this graph usually contains a map - for this reason it is capable of being positioned independent of the other components. On this graph you can move and resize the background, on some other graphs you can't.

The Title Box and Index Box are set using the Title and Index Box dialogues, the background is set by the Background Dialogue.

Resizing the Components

Switch to Use Mode.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized automatically to enclose the components

Clipboard Usage

When the sheet is in Use Mode, the graph can be copied as a picture to the clipboard and a picture can be pasted into the graph for use as the background or as a marker.

Usage Example

The file Density.Cln contains an example of this object in use.

Dialogues supported

 Number Format	Controls how numbers are displayed

 Number of Row/Cols	Sets the number of rows/columns in a grid

 Grid Style	Sets the style and spacing of the grid

 Background	Sets the style of the background

 Object Attributes	Sets the object's tags and name

 Map Style	Sets the type of Density Mapping

 Title	Sets the text and style of the title

 Index Box	Sets the style of the Index Box

Special Notes

There is an input version of this graph to allow you to paint geographic data into a sheet. See Density Graph (Input).


Density Graph Input Object
 Density Graph (Input)

Introduction

The Density Graph is used for painting values onto a geographic area (usually a map). It has a number of properties which you should consider before deciding if it is appropriate:

It produces a two dimensional array of numbers

The data is interactively painted onto the graph

The display is imprecise, you cannot read values on the graph to a high degree of accuracy

This object is usually used in conjunction with the Density Output Graph.

Frame Style

The frame has 4 outlets, to allow pipes to be taken off in 4 directions.

Any number of pipes can be taken off the frame, all of these pipes will be assigned the same value by this object.

The Components of the Graph

The graph consists of four separate parts, the main part is the plot grid, this section is where the density data is drawn. The index box shows a key, which details the density map style, the Title Box displays the title of the whole graph and finally the background is drawn behind the other components.

The background on this graph usually contains a map - for this reason it is capable of being positioned independent of the other components. On this graph you can move and resize the background, on some other graphs you can't.

The Title Box and Index Box are set using the Title and Index Box dialogues, the background is set by the Background Dialogue.

Resizing the Components

Switch to Use Mode.

Switch the Paint Mode to Move and Resize Components.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized automatically to enclose the components

Painting Data

Switch to Use Mode

Switch the Paint Mode to Paint the Data

Enter the Value to Paint with

Click with the mouse to paint

You can press the mouse button and keep it pressed to paint several squares

Clipboard Usage

When the sheet is in Use Mode, the graph can be copied as a picture to the clipboard and a picture can be pasted for use as a marker or background.

Usage Example

The file Density.Cln contains an example of this object in use.

Dialogues supported

 Number Format	Controls how numbers are displayed

 Number of Row/Cols	Sets the number of rows/columns in a grid

 Grid Style	Sets the style and spacing of the grid

 Background	Sets the style of the background

 Object Attributes	Sets the object's tags and name

 Map Style	Sets the type of Density Mapping

 Title	Sets the text and style of the title

 Index Box	Sets the style of the Index Box

 Density Paint Mode	Determine what value is being painted onto the Graph.

Special Notes

There is an output version of this graph to to display geographic density data, See Output Density Graph.


Pie Chart Object
 Pie Chart

Introduction

Calling this object a Pie Chart is misleading. It is a radially segmented graph (segments taken radially out from the centre of the graph). There is not restriction on the shape of the chart, it does not have to be circular, it is called a Pie Chart only because that is a familiar description to use.

One chart is allowed per object - to obtain several charts, use several pie chart objects.

This object covers both 2 dimensional and 3 dimensional graph types. A 2 dimensional pie chart is simply a 3 dimensional pie chart viewed straight down.

Frame Style

There are 4 inlets on the frame, but only one can be connected at any one time  - since only 1 data set can be displayed at any one time on this chart.

Notice that if the graph is resized, any pipes connected to the right and bottom inlets will be adjusted.

Clipboard Usage

When in Use Mode, this chart can be copied as a picture to the Clipboard and a picture can be pasted into the background, crust, filling or edge of the chart.

The Components of the Graph

The graph consists of four separate parts, the main part is the chart area, this section is where the pie chart is drawn - the chart is sized to fit within this section.

The index box shows a key, which relates the segments to their names, this information can also be displayed around the edge of the pie chart. The Title Box displays the title of the graph and finally the background is drawn behind the other components.

All of these segments can be moved and sized independently, the frame of the object is automatically sized to enclose all the parts inside.

Notice that the Pie Chart itself consists of a Crust, an Edge and a Filling. Each of these parts of a segment can be controlled separately.

Pulling a Segment Out

Switch to Use Mode

Move the mouse cursor over a segment

The cursor will change shape

Drag the segment out from the centre

The Pie Chart will change size to allow room for the segment

Resizing the Pie Chart

Switch to Use Mode.

Click with the mouse on the part of the graph to resize, to resize the Pie Chart, you must click on the plot area.

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized automatically to enclose all of the components of the graph.

If the plot area was resized, then the pie chart will be scaled to fit the new plot area.

Segmenting a Picture

To construct a segmented picture chart:

Drop a Pie Chart object onto the sheet and plumb it in

Switch to Use Mode

Copy the Picture to the Clipboard from your graphics package

Paste the picture into the Crust of the Pie Chart

Select Pie Chart Style.

Select Shape on this dialogue

Trace around the picture to obtain its shape.

Pull out any segments required

Acceptable Pictures

There are limits on which pictures can be handled by CleanSheet and which can't. It is all to do with the shape. For a shape to be acceptable its centre point must be inside the picture, and a line traced from the centre to infinity must only intersect one edge.

The centre is marked with a cross. A line traced from this point out to infinity only intersects one edge regardless of the direction it takes.

The second shape is unacceptable on 2 counts, the centre is outside the picture and tracing a line from the centre either gives 2 intersections or no intersections.

Usage Example

The file Pie.cln contains samples of the Pie Chart, this is by no means a complete list of all variations, but gives a useful set of suggestions.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Background	Sets the style of the background

 Title	Sets the text and style of the title

 Index Box	Sets the style of the Index Box

 Pie Chart Style	Sets the display style of the Pie Chart

 Pie Chart View	Sets the elevation, depth and first angle

Special Notes

There is a similar object called the Segment Chart which is an axially segmented graph (segments taken along an axis).

When you paste a picture into the Crust of this object, it is drawn using Windows region drawing commands. These are limited and may not print correctly on large pie charts. If your printout is wrong, then reduce the size of the pie chart.

Comparison with Traditional Spreadsheets

It is normal to have 2D and 3D graphs listed separately, together with a separate listing for pie charts with segments pulled out. This is purely for marketing, CleanSheet lists these graph all under the one object.

Background Information

The thinking behind allowing other shapes to be segmented is that, the most important thing about a Pie Chart is the angles, not the shape. The circle is simply to help you judge the angles. Given that this is the case, it would be nice to section other things, for example, company logos, flags and so on to give a much stronger impact to the graph.


Segment Chart Object
 Segment Chart

Introduction

This is an Axially Segmented Chart which put simply means a chart that is chopped into segments along an axis. Contrast this with the Pie Chart which is radially segmented from its centre.

One chart is allowed per object - to obtain several charts, use several chart objects.

This object covers both 2 dimensional and 3 dimensional graph types. A 2 dimensional chart is simply a 3 dimensional chart without any depth.

Frame Style

There are 4 inlets on the frame, but only one can be connected at any one time  - since only 1 data set can be displayed at any one time on this chart.

Notice that if the graph is resized, any pipes connected to the right and bottom inlets will be adjusted.

Clipboard Usage

When in Use Mode, this chart can be copied as a picture to the Clipboard and a picture can be pasted into the chart for use as the background, crust, filling or edge.

The Components of the Graph

The graph consists of four separate parts, the main part is the chart area, this section is where the segment chart is drawn - the chart is sized to fit within this section.

The index box shows a key, which relates the segments to their names, this information can also be displayed along either edge of the chart, or indeed inside the segments themselves. The Title Box displays the title of the graph and finally the background is drawn behind the other components.

All of these segments can be moved and sized independently, the frame of the object is automatically sized to enclose all the parts inside.

Notice that a segment itself consists of a Crust, an Edge and a Filling. Each of these parts of a segment can be coloured independently.

Resizing the Segment Chart

Switch to Use Mode.

Click with the mouse on the part of the graph to resize, to resize the Segments Section, you must click on the plot area.

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized automatically to enclose all of the components of the graph.

If the plot area was resized, then the Segment Chart will be scaled to fit the new plot area.

Segmenting a Picture

To construct a segmented picture chart:

Drop a Segment Chart object onto the sheet and plumb it in

Switch to Use Mode

Copy the Picture to the Clipboard from your graphics package

Paste the picture into the Crust of the Segment Chart

Select Segment Chart Style.

Select Shape on this dialogue

Trace around the picture to obtain its shape.

Acceptable Pictures

There are limits on which pictures can be handled by CleanSheet and which can't. It is all to do with the shape. When the segment chart is constructed, lines perpendicular to the axis line ar intersected with the shape. These lines must intersect at no more and no less than 2 places.

The axis line is shown in red. The perpendicular lines (shown in blue) intersect the shape at only 2 points.

The second shape is unacceptable, notice that the blue perpendicular line can intersect more than 2 faces of the shape.

Usage Example

The file Segment.cln contains samples of the Segment Chart, this is by no means a complete list of all variations, but gives a useful set of suggestions.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Background	Sets the style of the background

 Title	Sets the text and style of the title

 Index Box	Sets the style of the Index Box

 Segment Chart View	Sets the axis angle, elevation and depth

 Segment Chart Style	Sets colour and style of the segment charts

Special Notes

When you paste a picture into the crust of this object, it is drawn using Windows region drawing commands. These are limited and may not print correctly for large charts. If your printout is wrong, then reduce the size of the chart.

This object can produce results which mislead. Read the discussion under Segment Chart View to see why.

Background Information

This chart is really intended for sectioning company logos, flags and other nearly rectangular shapes. Other shapes aren't really suitable because the axis angle has to run parallel to one side and perpendicular (or perceived as perpendicular in the case of 3D views) to another side. Without these conditions it produces uneven looking segments.


Line/Bar/Area Graph Object
 Line/Bar/Area Graph

Introduction

The Line/Bar/Area graph displays series of data within horizontal intervals. There are several things that are important about this graph:

It is scaled in only 1 direction (across), if your data consists of coordinates on an XY graph, you should use the XY Scatter Graph.

Several graphs can be overlaid onto each other

Graphs can be stacked horizontally

Graphs can be displayed as a percentage of the total

This object is the horizontal version of the Line/Column/Area Graph. It is functionally identical - if you are familiar with that object, then this object works almost exactly the same way.

Frame Style

There can be up to 8 series overlayed on this graph object, each series can be piped in separately, or alternatively a two dimensional array can be put into the 'Full' inlet, this two dimensional array is broken down into separate series.

The interval names inlet is to input the names given to the horizontal intervals on the graph.

Individual Series Inlets

The inputs data for these is the data for one series only, the inlet you attach it to determines which series the data is for  - attached to inlet A and that is the data for Series A.

This graph object expects a 1 dimensional array of data into these inlets, however it can process two dimensional arrays to achieve the result it expects.

Full Inlet

The full inlet is used when all the series are in a two dimensional array. This array can contains interval headings, titles and so on - the graph object analyses the array and decides what is what.

When a title is identified it is used for the appropriate headings.

If the titles are not being used correctly, if may be that the 'Get Names from Input' option is set (see General Options), if it is, then CleanSheet will expect to get names from the 'Interval Names' inlet.

You cannot mix Series Inlets with the Full Inlet, one or the other can be connected, CleanSheet will not allow you to connect both.

The Components of the Graph

The graph consists of many separate parts, the main part is the plot area, this section is where the data series are drawn. The index box shows a key linking the series to its name, the Title Box displays the title of the whole graph.

That leaves the background. For this graph object, the background is purely decorative and so it occupies the whole of the background to the graph and cannot be resized separately. Notice that the intervals labelled 'C' on the graph are the same size. The background adds the same amount of gap above and below the plot area in order to make the graph look nice. This means that if you want a larger gap below the plot area, you must move the plot area down.

The Title Box and Index Box are set using the General Options dialogue.

Resizing the Components

Switch to Use Mode.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The background and frame will be resized automatically

Clipboard Usage

When the sheet is in Use Mode, the graph can be copied as a picture to the clipboard and a picture can be pasted into the graph for use as a filling, background, or marker.

Usage Example

The examples Graph3.cln contains examples of the use of this object. This is not a complete list, just a few suggestions.

Dialogues supported

 Number Format	Controls how numbers are displayed

 Object Attributes	Sets the object's tags and name

 Grid Style	Sets the style and spacing of the grid

 Axis and Grid	Sets the style of the grid and axes

 Background	Sets the style of the background

 Series Options	Sets the style of each series

 Scaling	Set the scaling

 General Options	Set option covering all of the graph

Special Notes

There is a complementary object called the Line/Column/Area Graph object which has exactly the same features as this object, but is a vertical graph.

The graph can display pictures pasted into Area series. Windows has a limitation that may cause large graphs to be drawn incorrectly during printing if you use this option. If this happens reduce the size of the graph until the picture is drawn correctly.

Comparison with Traditional Spreadsheets

This object covers a whole range of percentage, stacked and overlaid graphs. Normally only the bar style graphs are allowed on a horizontal graph. This was an inconsistency which was not copied for CleanSheet, any graph on the vertical style Line/Column/Area graph can be reproduced on the horizontal version.

For stacked graphs, select 'Stack onto Similar Objects' which will stack the select graph style onto graphs that are the same style. This is selected on the Series Options dialogue and must be selected for each of the data series that will be stacked.

For percentage graphs, select 'Percentage Scaling' on the Scaling dialogue.

For logarithmic graphs, select 'Logarithimic' on the Scaling dialogue.


Polar Graph (Output) Object
 Polar Graph (Output)

Introduction

Whereas the XY Scatter Graph plots points onto a Cartesian (xy) space, the Polar Graph plots points onto r, theta space. Essential it plots radii against angles.

This graph can have up to 8 data series plotted onto it at the same time, each series with its own plot style.

Frame Style

The frame has two main entry points. The Full Inlet allows a two dimensional array into the graph. This array is interpreted by the graph into several data series. The Separate Series inlets, allow one series per-inlet.

You cannot connect both the Full Inlet and the Separate Series inlets at the same time.

Full Inlet

The full inlet expects a two dimensional array, if it detects column headings it will remove them and use them as series names.

If you include titles in the table they must be string objects (See Data Types). Notice in the above example that the angles only appear once. The first column is taken to be the angles and the next 3 columns are the radii plotted against each of those angles.

For example series 'R2' has the 3 points in it, {angle 100, radius 40} {angle 150, radius 50} and {angle 200, radius 10}.

In this example, the column headings for "R1" to "R3" are taken by the polar graph and used as the series names.

This example produces exactly the same data points as the previous example. The difference is the omission of the column headings.

Separate Series Inlets

These inputs allow data series to be input, series by series. Each Inlet 'A' to 'H' corresponds to the plotted series 'A' to 'H'.

This gives you much finer control over the plotted data. For example the Full Inlet has only one set of angles to plot against, while the separate series Inlets plot against several sets of angles.

These inputs require 2 columns of data, the first column is the angle and the second columns is the radii. The above table corresponds to 3 points {angle 100, radius 70}, {angle 150,radius 40}, {angle 200, radius 20}.

Headings are not allowed for these inputs.

Plotting Equations onto a Polar Graph

The Polar Graph can recognise when equations are being fed into it. It can also use string objects which are easier to enter into CleanSheet. The equations are plotted against all the angles in a circle and the result plotted on the chart.

For example, the string object "200*sin(x)" fed into inlet A will plot a circle of diameter 200 onto the graph for series A.

Notice that the graph must be in radians for this to work, since sin(x) takes x in radians - radians or degrees are set on the Polar Axis and Grid dialogue. The function is always be a function of x.

See Polar3.cln for an example of equations into a Polar Graph.

The Components of the Graph

The graph consists of four separate parts, the main part if the plot area, this section is where the data series are drawn. The index box shows a key linking the series to its name, the Title Box displays the title of the whole graph.

The background is drawn behind the other sections of the graph.

Resizing the Components

Switch to Use Mode.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized to enclose the components of the graph

Clipboard Usage

When in Use Mode, the graph can be copied as a picture to the clipboard and a picture can be pasted into the graph for use as a background.

Usage Example

The file Polar1.cln contains examples of some of the styles available with this graph. The file Spiral.cln contains an example of its use. Polar2.cln demonstrates the difference between the input, output and calculation Polar graphs. Finally Polar3 demonstrates plotting equations onto Polar Graphs.

Dialogues supported

 Number Format	Controls how numbers are displayed

 Background	Sets the style of the background

 Title	Sets the text and style of the title

 Index Box	Sets the style of the Index Box

 Object Attributes	Sets the object's tags and name

 Polar Scaling	Set the scaling used by a Polar Graph

 Polar Axis and Grid	Set the style of the axes and grid

 Polar Series Options	Set the style of each data series.

Special Notes

There is no logarithmic version of this graph since it is an mathematical impossibility to have a logarithmic version of a polar graph. If your polar graph is really an XY graph with the X axis wrapped in a circle, then preprocess the data with a Cog object to obtain the Log of the values before feeding it into a polar graph object.

Comparison with Traditional Spreadsheets

Some spreadsheets support Polar Graph types and CleanSheet's Polar Graph may therefore be familiar to you. The main difference is the object orientated nature of CleanSheet allows equations to be fed into this graph (and also into the XY Scatter Graph). These equations are evaluated and plotted.


Polar Graph (Input) Object
 Polar Graph (Input)

Introduction

The Polar Graph Input is the input variation of the Polar Graphs. It inputs an array of the form {r, theta} into a sheet where r is the distance from the centre and theta the angle subtended by the line drawn to the centre.

It is a very mathematical input device, if you want a more natural input mechanism the Tumbler object or Slider object may be more appropriate.

Notice that this object inputs 2 numbers at the same time. This is a key property of this object, the sheet is only recalculated once for each point you input.

Frame Style

The frame has 4 outlets, to allow pipes to be taken off in 4 directions.

Any number of pipes can be taken off the frame, all of these pipes will be assigned the same array by the Polar Input object.

The Components of the Graph

The graph consists of several separate parts. The main part is the plot area, this is the area in which you place a point. The Title Box contains the title of the graph. The background is drawn behind the other parts of the graph.

Resizing the Components

Switch to Use Mode.

Set the Graph Paint Mode to Move and Resize the components.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized to enclose the components of the graph

Plotting the Input Point

Switch to Use Mode

Set the Graph Paint Mode to Paint the Data

It is advisable to set the Scale of the Polar Graph.

Click with the mouse on the Plot Area, the point will be drawn.

 To input a negative radius hold down the Shift Key. The blue marker point will turn Red indicating that the point has a negative radius.

Clipboard Usage

When in Use Mode, the graph can be copied as a picture to the clipboard and a picture can be pasted into the background of the graph.

Usage Example

The file Polar2.cln demonstrates the difference between the input, output and calculation Polar graphs.

Dialogues supported

 Number Format	Controls how numbers are displayed

 Background	Sets the style of the background

 Title	Sets the text and style of the title

 Object Attributes	Sets the object's tags and name

 Polar Scaling	Set the scaling used by a Polar Graph

 Polar Axis and Grid	Set the style of the axes and grid

 Graph Paint Mode	Set painting or sizing of graph components

Special Notes

If you need to input Cartesian XY data, there is an object - the XY Scatter Input object that is more suitable.


Polar Graph (Calculation) Object
 Polar Graph (Calculation)

Introduction

This object is part of the family of Polar Graphs. It is used for calculating results given a function drawn as a curve on the graph. When you have an equation that represents a function it is a simple matter to use that equation within a Spreadsheet. When you have an irregular curve that represents a function, you either have to approximate that function, use tables of data or as in CleanSheets case, you can draw the curve directly and use that. This object is for Polar Empirical Functions.

To use this object, you must first draw or trace the function. (See Tracing a Function). Once this is done, angles fed into this object are converted to their equivalent radius by reference to the graph. For angles that lie between points you have traced, the radius is linearly interpolated.

Frame Style

The frame has 4 inputs and 4 outputs. Only one of the inputs can be connected at any time. Any number of pipes can be taken off the outputs - they are all the same.

The 4 inputs are simply to allow easy access from all 4 directions.

The Components of the Graph

The graph consists of several separate parts. The main part is the plot area, this is the area in which you draw the curve that represents the function. The Title Box contains the title of the graph. The background is drawn behind the other parts of the graph.

Resizing the Components

Switch to Use Mode.

Switch the Graph Paint Mode to Move and Size Components.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized to enclose the components of the graph

Painting the Function onto the Graph

Switch to Use Mode

Switch the Graph Paint Mode to Paint the Data

Click with the mouse to paint a point

Move the mouse over an existing point and click and drag to move that point

Clipboard Usage

When in Use Mode, the graph can be copied as a picture to the clipboard and a picture can be pasted into the background of the graph.

Conversion

A single angle fed into this object is converted to a single radius.

For example the angle 20 could convert to the radius 10. The angle is in degrees or radians, according to the settings on the Polar Axis and Grid dialogue.

When an array is fed in, it is taken as an array of angles. Each angle is converted in-tern, the result is an array of the same type.

Example:

{{20,10,50,60},10} could convert to {{10,40,20,60},90}. The numbers would be taken as 20 degrees, 10 degrees and so on, converted into the radii that correspond to those angles and the result assembled into an identical style of array.

Usage Example

The file Polar2.cln contains an example of the Polar Calculation Object working.

Dialogues supported

 Number Format	Controls how numbers are displayed

 Background	Sets the style of the background

 Title	Sets the text and style of the title

 Object Attributes	Sets the object's tags and name

 Polar Scaling	Set the scaling used by a Polar Graph

 Polar Axis and Grid	Set the style of the axes and grid

 Graph Paint Mode Set painting or sizing of graph components

 Polar Points	Edit the data points in the curve

Special Notes

An XY Scatter Graph equivalent for XY Function Curves.


 Database Filter

Introduction

The Filter object takes an input (usually an array), performs a test on parts of it and then allows those parts through that pass the test, removing the ones that don't. It filters out records from an array. This introduction is vague because the object has so many possible actions depending on its settings on the Filter Type dialogue. You should ensure you are familiar with that dialogue before using this object.

A typical example of a filter object in action is shown below. The input table is filtered to allow only rows where item 1 of the row is between 400 and 1500.

There are only 2 rows that match this rule, hence only 2 rows are allowed through.

Frame Style

The frame has 4 outlets, these are all the same - they provide the results after filtering has taken place.

The main inlets are where the input array is fed in. Either of the 2 main inlets can be connected, 2 are provided simply to make the object easier to plumb in.

At the top and bottom of the frame is Parameter A and Parameter B. Consider a filter of type A<Data<B. Normally A and B would be entered on the Filter Type dialogue, however you can set the Filter to get these parameters from the inlets A and B on the object frame.

Usage Example

The file Database.cln gives examples of the use of the filter object within a mixed database/calculation sheet.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Filter Type	Set the filtering action required

Special Notes

The Filter Object performs a test on elements of an array and either passes them, or rejects them. If the action you require is looking up elements of one table in another table, then the Lookup object is more suitable.


Database Sort Object
 Database Sort

Introduction

The Database Sort object, takes an input array, sorts it according to a specified rule and outputs the results. The sorting rule is set by the Sort Type dialogue- You should be familiar with this dialogue before using a Sort Object.

The Basic Types of sort are:

Sort in Ascending Order

Sort into Descending Order

Sort by Vague Logic Comparison - Nearest first

Sort by Vague Logic Comparison - Nearest last

This dialogue requires a two dimensional array as input and outputs a two dimensional array as result.

Examples

Ascending Order

Here we are sorting columns in terms of row 0.

The columns are rearranged so that the first row is in ascending order. Since the first row contains strings, ascending order mean alphabetic order.

Descending Order

Here were are sorting columns by reference to row 1 (the row containing the numbers).

Notice that the second row is now in descending order, and that row 0 has also been rearranged to keep the columns correct.

Nearness

Here we are sorting the rows by reference to column 0 (the column containing the names). The test for nearness compares how similar two objects are, this requires a comparison object. The comparison object we are going to use is the string "Johnstone".

The first column is now in descending order of similarity, "Johnson" is nearer than "Jones" is nearer than "Smith".

You may be thinking that to find the nearest matching object from a table, you only have to sort it for nearness, then take the first entry. This would work, but a far simpler way is to use the Lookup Object, which has a Nearest option.

Farness

This is the reverse of the nearness sort. The worst match appears first in the list, the best match appears last. This can lead to some strange result, for example consider the following table, where column 0's entries are being sorted in terms of how far they are from "Smith".

Notice that the date object comes first in the list. It is a completely different object type and so is bound to be the furthest away from the string object "Smith".

Frame Style

The frame has 4 inputs and 4 outputs. Only one of the inputs can be connected at any time. Any number of pipes can be taken off the outputs - they are all the same.

Usage Example

The file Database.cln contains an example of the use of this object.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Sort Type	Set the rules by which this object sorts


 Database Comparator

Introduction

The database comparator compares two input objects and return TRUE if they are the same. It uses the same compare mechanism as CleanSheets normal = operator.

Frame Style

The frame has 4 outlets that are all the same, any number of pipes can be taken off these outlets.

There are two different types of inlet, Inlet's A and B, these represent the two parameters being compared.

Usage Example

In this example the Comparator is comparing two date object to see if they are the same.

Notice that the dates are entered in different formats, but nevertheless they represent the same date - they are the same, so the result is TRUE.

Dialogues supported

 Object Attributes	Sets the object's tags and name

Special Notes

You could produce an equivalent to this object by using a calculator object and writing a test within it. However this would give no indication to the user of the sheet that a comparison is taking place, one calculation object looks exactly like another. It is better to use this object when performing a comparison within a database, as it makes the sheet much clearer.


This is a Data Object Input box, it is used here, to input a date into the sheet.


This is a Data Object Input box, it is used here to input a date into the sheet.


This is a Comparator object, which compares the two objects (in this example dates) to see if they are the same.


This is an Output Table object used to display the result of the comparison.


Database Splicer Object
 Database Splicer

Introduction

The Database Splicer, joins arrays together by a simple splicing system. It does not care what is in the arrays, they are normally Database results hence the name, but they can be anything.

In cases like the example in Database.cln where two database fragments contains duplicates which have to be fixed during the merge process, the Database Merge object is more suitable.

Frame Style

There are 8 inlets which represent 8 arrays that can be spliced together with one object. The inlets are labeled A, B, C to H - this is the order that they are joined, A will become the left most column, or the top most row of the finished array. Only one pipe can be attached to each inlet.

There are 4 outlets, any number of pipes can be taken off these. The outlets pass the results out to the rest of the sheet.

Usage Examples

This objects modes of operation is covered in great detail in the Splice Type dialogue.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Splice Type	Sets the type of array splice required

Special Notes

This is a simple object for splicing data together, but it is by no means the only manipulation object. See Also Overlay Object, Database Merge,  and even the Calculator Object and the Cog object can be used to manipulate arrays, but with some effort in designing the equations.


Database Chopper Object
 Database Chopper

Introduction

The database object takes an array and slices it into rows or columns. It is designed to complement the graph objects and database objects. For example it has 8 outputs which is the maximum number of data series that can be plotted on one graph.

All the options available with this object are discussed in the Type of Array Chop dialogue.

Frame Style

There are 4 inlets, but since there can only be one input to this object, only one of them can be connected at any time.

There are 8 outlets, labeled A,B,C..H. Outlet A is the first fragment from the array, B the second and so on.

You may think you are restricted to 8 fragments, but in fact you can use several of these objects and extract as many fragments as you require.

Usage Example

This is an example of the Database Chopper working along with a graph object. Three data series are fed into the Chopper, a pipe is taken off the C outlet, which corresponds to the 3rd data series {10,20,30,40} and this is sent into the Pie Chart for display.

Click on any part you need further help with.

This is a typical example, a Graph object can accept separate series into the Series Inlets and the Chopper Object can prepare individual series from an array.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Type of array Chop	Specifies the action of the array chop object


This is an Input Table object, used to input the data series.

For the purposes of this example, you are asked to imagine that this array is the result of a calculation within a sheet.


This is a Database Chopper, here it is set to split the input array into columns of data, starting at column 0.

Hence Outlet A is {100,300,400,500}

Outlet B is {600,700,800,900}

and Outlet C is {10,20,30,40}


This is a Pie Chart object, used here to display the result of the Chopper Object.


 Database Trimmer

Introduction

It is quite common to have column and row headings attached to an array of data. This object strips off those column and row headings and makes the parts available at 4 outlets. This is a useful step in processing prior to sending data into a graph object.

Outlet D is the Title of the Table, it is output as a single object (in this example the string "Title"

Outlet A is the Column Headings, output as a 1 dimensional array. In this example {"Series A","Series B","Series C"}.

Outlet B is the main body of the table output as a 2 dimensional table. {{120,183,128,183},{34,54,564,453},{432,433,354,897}}

Outlet C is the Row headings, output as a 1 dimensional array. In this example {"Yr 1990","Yr 1992","Yr 1993","Yr 1994"}

Frame Style

The four inlets are all the same, any one of them can be connected as the input.

The outlet A, B, C and D correspond to the 4 parts of the table that are output.

Usage Example

In this example the same table is sent to two graphs. The first graph has the complete table fed into it, the second has only the data section sent to it. Notice that the first graph takes the row headings as interval names (it also takes the Column headings as series names and the title as the title of the graph). If you have set these manually on the graph they would now be overwritten, hence you may want to use this object first.

Click on any part you need further help on.

Dialogues supported

 Object Attributes	Sets the object's tags and name

Special Notes

If the data comes direct from an Input Table, you can remove the column and row headings before the data is passed into the sheet using the Input Table Options dialogue.

This object is a specific implementation of the Array Dissector Object. If it doesn't work the way you want it to, don't force it, simply use the full Dissector object.


This is an Input Table object, used here to provide data for our example. The first row and first column contain string objects, the rest of the table is numbers.

The Input Table has an option to strip the column and row headings. If your data comes from an Input Table and you do not need the column and row headings then it is simpler to remove the headings at source.


This is a Line/Column/Area Graph.


This is a Line/Column/Area Graph.


This is the Trimmer object, notice that only the data (section B) is being used in this example.


 Database Extractor

Introduction

The Extractor extracts a section from a 2 dimensional array. It is a much simpler version of the Array Dissector, and in cases where the power (and complexity) of Dissector is unnecessary you can save yourself time by using this object.

An input two dimensional array goes into the object, a rectangular section of that array is taken out and the resulting two dimensional array is returned.

The Rectangular section is set by the Set Extraction Section dialogue.

Frame Style

The frame has four inlets and four outlets, only one inlet can be connected since there can only be one input into this object.

Any number of pipes can be taken off the outlets. All of the outlets are the same.

Usage Example

The file Database.cln contains an example of this object in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Area to Extract	Set the Extract Section


 Curve Fit Object

Introduction

The Curve fit object takes a set of XY data points and fits a line or curve to those points. The return from this object is an equation object for the line or curve.

This equation object can be used directly using the Evaluator Object, or you can send it to an Output Table for display, or alternatively plot it directly on a graph such as the XY Scatter Graph.

Available Curve Fits

Straight lines y=mx+c

Exponential Curves y=be^x

x -Square Curves y=bx^2

Polynomial Curves of order 2 to order 14

These curves are explained more completely in the Curve Fit Type dialogue.

Frame Style

The frame has four inlets, only one of which can be connected at any one time.

The four outlets are all the same, they provide the equation (as an equation object).

Acceptable Inputs

The Curve Fit object requires either an array of XY pairs such as {{100,200},{300,400},{500,600}...} or it can detect arrays of X's and Y's such as {{100,300,500...},{200,400,600...}} and transpose them.

Usage Example

The file Xyscat.cln contains an example of curve fitting.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Curve Fit Type	Set which curve type to fit

Special Notes

You do not need to approximate function curves using this object. If you prefer you can draw them directly to a calculation graph object and use the curve directly.

The Polynomial curves require more data points than their order, for example a polynomial of order 5 requires at least 6 unique data points.

Comparison with Traditional Spreadsheets

This is comparable to the line and exponential curve fitting functions on most spreadsheets. The reason polynomials are not normally available is because it's very difficult to describe a polynomial on a spreadsheet that doesn't support equation objects.


Converter Object
 Converter

Introduction

The Converter converts one data type to another data type. Inherent in this conversion is a whole set of powerful operations, including:

Converting Numbers to Strings

Evaluating Equations

Converting Strings representing numbers to numbers

Converting Strings representing dates to dates

For a complete list of the conversions available, see the Conversion Type dialogue.

Frame Style

There are four inlets, only one of which can be connected at any one time.

The result of the conversion appears at all of the four outlets.

Usage Example

The following example uses the Converter to convert from dates to number of days since 1900.

Click on any part you need help with.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Number Format	Sets the format for conversion of numbers to strings

 Date Format	Sets the format for conversions of dates to strings

 Time Format	Sets the format for conversion of time object to strings

 Complex Format	Sets the conversion format for complex numbers

 Conversion Type	Defines the type of conversion


This in an Object Input Box used to input the dates.


This is the data converter. It is set to convert input objects to Integers, and hence will convert a date object to the number of days since 1900.


This is an Output Table object used to display the finished result.


 Lookup Object

Introduction

The data lookup object, searches for one object within another - it lookups a value from a table. There are three rules which define its action:

What does it consider a match? A lookup object can index into a list, find a nearest match, find an exact match or an approximate match - the choice is yours.

Where to look in the table? Which column or row it should look in.

Having found a match what next? Does Lookup return the row, column, item of data or a Boolean TRUE to indicate that there was a match?

These three rules are defined by the Data Lookup Type dialogue.

Frame Style

The frame has 4 outlets that are all the same, any number of pipes can be taken off these outlets.

There are two different types of inlet, Inlets A and B,

A	Is the item (or array of items) being looked up.

B	Is the Table being looked into.

Usage Example

The example Lookup1.cln demonstrates a lookup object, indexing into a table. The example Lookup2.cln demonstrates the Nearest option to locate records from a database.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Lookup Type	Defines the rules by which objects are looked up

Special Notes

This is a key object within CleanSheet, it is worth the effort to understand it.


 Evaluator Object

Introduction

The Evaluator Object evaluates an equation for a set of values. The equation can come from anywhere but usually comes from a Curve Fit object. The combination of a Curve Fit and an Evaluator object constitutes an Empirical function - a function defined by observed data rather than an equation.

Consider the following example:

The array {10,20,30} is fed into Inlet B, the equation "2+3*x" is fed into inlet A, the result from the Evaluator object is {32,62,92}.

Notice that the equation doesn't strictly have to be an equation object, a string object will do (see data types).

The Evaluator object returns the result in the same form as the original data, if a column array {{10,20,30}} has been passed then the result would similarly be a column array with two sets of curly brackets {{32,62,92}}.

The equation is assumed to be a function of variable x.

Frame Style

The frame has 4 outlets that are all the same, any number of pipes can be taken off these outlets.

There are two different types of inlet, Inlets A and B,

A	Is the equation or string object

B	Is the values to evaluate the equation for

Usage Example

The Emp2.cln contains an example of an equation mapped empirically using this function.

Dialogues supported

 Object Attributes	Sets the object's tags and name

Comparison with Traditional Spreadsheets

A common function in spreadsheets is the TREND command for calculating a trend. This is a very restricted command, limiting you to straight line approximation and only handling a row or column (i.e. a 1 dimensional array). The combination of the Curve fit and Evaluator object has the same functionality as Trend, but with much more freedom on the data.


AB To C Switch Object
 AB to C Switch

Introduction

The AB to C switch, switches data between two pipes under control of the user of the sheet. It has two inputs A and B and one output C,  depending on the state of the switch either A is connected to C or B is connected to C.

To change the state of the switch from A to B and vise versa, click on the button in the centre of the object (in Use Mode), the button will change state.

The current state of the switch is indicated by the Icon A or B displayed in the centre of the switch.

Frame Style

The frame has two possible inlets for A and two for B. Only one pipe can be connected to an A inlet and only one to a B inlets, there are two of each simply to make it easier to plumb the object in.

There are 4 outlets that all carry the result of the switch - any number of pipes can be taken off these.

Keyboard controls

When in Use Mode and when the object is selected, the space bar will change the state of the switch.

Usage Example

Consider an example where a price is entered into a sheet. The price can include Vat (UK Sales Tax at 17.5%) or excludes Vat. A switch is used to indicate if the price includes or excludes Vat.

Here the switch is set to A, the price excludes vat and so the value passes straight through to the rest of the sheet (in this example it goes straight to an Output Table). Notice that the pipes are coloured yellow only to help you see where the data flows in this example.

Here the switch is set to B, the price goes through the calculation object which adds tax and is then fed through to the rest of the sheet.

Dialogues supported

 Object Attributes	Sets the object's tags and name

Special Notes

If you need many states, or many inputs and outputs, use the Switch Object together with a Button Group.

There is a version of this switch with one inlet and two outlets, see C to AB Switch.

Background Information

It electronics this switch is a single-pole-double-throw switch, but limited so it flows one way. You may think this is restrictive, but this is not electronics, this is data flowing and one of the data types is an array. If you need to switch many parameters at once, then switch an array.


This is an Object Input Box, used in this example to input a number.


This is an AB to C switch, used here to switch between the price and the price with Vat added on.


This is a Calculator Object, the equation is contains is simply A*1.175 which simply adds Vat at 17.5% to a price.


This is an Output Table, used here to display the result of the switch group, in a real sheet this result would go on to be used in the main part of the calculation.


 C to AB Switch

Introduction

The C to AB Switch connects one input C to one of two outlets A or B. The switch is under user control, to change its state, the user clicks in the centre with the mouse (the sheet must be in Use Mode).

The state of the button is indicated by an A or a B in the centre of the object.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time. This inlet is switch contact C.

There are two of each of the outlets A and B, you can take any number of pipes off these outlets.

Keyboard controls

When in Use Mode and when the object is selected, the space bar will change the state of the switch.

Usage Example

The example Database.cln contains an example of the C to AB switch in use in a sheet.

Dialogues supported

 Object Attributes	Sets the object's tags and name

Special Notes

If you need many inputs or outputs, or special switching patterns then use a Switch Object in combination with a Button Group object.

There is a version of this switch with 2 Inputs and 1 Output, see AB to C Switch.


Counter Object
 Counter

Introduction

The counter object counts the number of rows, columns or elements in the input data and returns the result as its output. What is counted is determined by the Counter Type dialogue.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time.

There are 4 outlets which can have any number of pipes connected to them.

Usage Example

A typical situation where a counter object is used is shown below.

Imagine that you had constructed a database query from Filter and Merge objects and wanted to print out the results. What if several hundred records matched the filter conditions - you would probably want to narrow down the filtering conditions until you have a more reasonable number before printing.

This is the sort of group of objects you would use. The counter object counts the number of matching rows (records) and when this is a reasonably small number, you could print it by changing the Switch to B.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Counter Type	Sets what to count


This is the Counter object, set to count the number of records in the incoming data,


This is an Output Table, used here to display the number of records found.


This is A to BC Switch. When this switch is set to B, the data can flow into the Hard Copy object and will be printed.


This is a Hard Copy object - it prints the data it receives to the printer.


Inverter Object
 Inverter

Introduction

The Inverter is the object level implementation of the Invert function. It has 2 main uses:

When the input data is an array, it is treated as a matrix and this object takes the matrix inverse of the array.

When the input data is Boolean TRUE or FALSE, it returns the inverse, e.g., FALSE becomes TRUE.

Obviously the second of these is the more common, the normal use for this object is to invert the result of Comparison objects.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time.

There are 4 outlets which can have any number of pipes connected to them.

Dialogues supported

 Object Attributes	Sets the object's tags and name


 Junction Object

Introduction

The junction object returns the input fed into it unchanged. It has no calculation use but it has a great deal of use when laying out a complex sheet. Consider an example where several pipes from the same outlet have to be taken a long way across a sheet. You may find it much easier (and neater) to take one pipe from the outlet to a junction object and then take several much smaller pipes from that junction.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time.

There are 4 outlets which can have any number of pipes connected to them.

Dialogues supported

 Object Attributes	Sets the object's tags and name


 Hard Copy Object

Introduction

When data is to be presented to the user on the screen you use an Output Table object. Where you want a printed copy you send the data to a Hard Copy Object which prints the data as a table to the currently set printer.

The data is printed each time a recalculation of its input pipe occurs - this could mean that each time you make changes this object would print a result out. If you do not want this, then use an AB to C Switch object or similar cutout to prevent the data flowing into the Hard Copy Object.

The table can either be printed as rows and columns or using array notation in exactly the same way that the Output Table object can.

If the table is bigger than the page, then it is chopped into segments and printed onto several pages.

The headers, footers and so on are set using the Hard Copy Settings dialogue. These are specific to each Hard Copy object.

The spacing of the grid is set using the Grid Style dialogue.

Frame Style

There are 4 inlets on the frame, but only one can be connected at any one time  - since only 1 data item can be printed at any one time.

The <###> Error

When there is insufficient space to print a number or object, an error marker is shown instead. When it is not possible to print the output value, Hard Copy Object will not try to display a partial result.

When you see the error marker, switch to Edit mode, and enlarge the space allowed for the columns or rows using the Grid Style dialogue. You can also switch on the Wrap option of the Alignment dialogue, which allows the text to be wrapped around in its cell.

Usage Example

The file Database.cln contains an example of this object in use.

Dialogues supported

 Font Selection	Selects the typeface style, colour and size

 Number Format	Controls how numbers are displayed

 Date Format	Controls how dates are displayed

 Time Format	Controls how times are displayed

 Complex Format	Controls how complex numbers are displayed

 Alignment	Controls alignment of text in each cell

 Grid Style	Sets the style and spacing of the grid

 Object Attributes	Sets the object's tags and name

 Hard Copy Options	Settings specific to the Hard Copy Object.

Special Notes

The Hard Copy Options dialogue has an option to print to file. When this is selected the output is a binary file that is formatted for the printer. If your aim is to get a table of data in a file that you can use in other programs, then use the Filing Clerk object.


Filing Clerk Object
 Filing Clerk

Introduction

The Filing Clerk takes data fed into it and writes it out to a file. The file is written on each recalculation, with the data either appended onto the end, or overwriting the previous version of the file.

Several text formats are available that can be used by many other packages, this makes it a useful way for transfering data.

If this object is set to append results onto the end of the file, then it can accumulate data from multiple  iterations of a loop.

The options available with a Filing Clerk are covered in detail on the Filing Clerk Options dialogue.

Frame Style

There are 4 inlets on the frame, but only one can be connected at any one time  - since only 1 data item can be filed at any one time.

Usage Example

The following example is a trivial example of a Filing Clerk used to store the data in an input object to a file.

The filing clerk is set to create tabbed columns as a result and produces a text file containing:

100	300

200	400

Dialogues supported

 Number Format	Controls how numbers are displayed

 Date Format	Controls how dates are displayed

 Time Format	Controls how times are displayed

 Complex Format	Controls how complex numbers are displayed

 Object Attributes	Sets the object's tags and name

 Filing Clerk Options	Sets options specific to the Filing Clerk


This is an Input Table object, used here to input a small table into the Filing Clerk object.


This is a Filing Clerk object, used to store the data to a file. For this example it is set to write a file called 1.txt, in tabbed column format.


 Database Merge

Introduction

The Merge Object, takes two arrays which contain database information and combines them into a single result array. It can merge the two arrays in several ways, for example checking entries to remove duplicates, or merging the two arrays so that only entries present in both are passed through. The rules by which the data is merged are set by the Merge Type dialogue, the topic on this dialogue explains all the available options in detail.

Frame Style

The frame has 4 outlets that are all the same, any number of pipes can be taken off these outlets.

There are two different types of inlet, Inlet's A and B, these correspond to the two databases being merged.

Usage Example

The example Database.cln contains an example of this object in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Merge Type	Set the rules used to merge the data

Special Notes

If you simply want to join two arrays together without any special processing, then you can do this by using a Database Splice object - this is much faster.


Switch Object
 Switch

Introduction

The switch object connects input pipes to output pipes according to a switching pattern which you set. The switch is not operated directly by the user, instead a control line determines which switching pattern is in use.

The list of switching states is set by the Switch Connections dialogue - this controls the links that are made between the inputs and outputs and also how many inputs and output contacts there are (up to 36 of each).

When an outlet isn't connected by the switch to an inlet, the Switch object assigns that outlet a Null.

Frame Style

Along the left side are the inlets that correspond to the switch contacts inlets (there are 3 in this example, but there can be up to 36).

Along the right side are the outlets for the output switch contacts (there is only 1 shown here, but, just as with the inlets, there can be upto 36).

The top and bottom inlets are the control inlets, the value coming into one or other of these determines which switch pattern is in use.

Usage Example

The file Switch.cln contains an example of the switch object in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Switch Connections	Sets the switching patterns

Special Notes

If you want a switching action under control from the user you can combine a Button Group object with the Switch Object.

Two simple predefined switches exists, the AB to C Switch and the C to AB Switch.


Random Generator Object
 Random Generator

Introduction

The random generator is used to pump random data into a sheet. The data is derived from an equation that is based on CleanSheet Rand function, by changing the equation, you can change the range and type of random data objects that the generator produces.

Frame Style

The frame has 4 outlets, to allow pipes to be taken off in 4 directions.

Any number of pipes can be taken off the frame, all of these pipes will be assigned the same random result.

Usage Example

The file Loaded.cln contains an example of this object in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Random Input	Sets the rules for random generation


Savings and Loans Object
 Savings and Loans

Introduction

The Savings and Loans object is used in calculating financial values for savings, loans, investments and annuities. The exact value it calculates depends on what you feed in - you provide what you know, this object fills in the blanks.

This is the object level implementation of the SAL function, you should be familiar with this function before attempting to familiarise yourself with the Savings and Loans object.

A typical loan or saving has the following parameters:

Present Value	The value at the start

Future Value	The value at some period in the future

Periods	The number of periods over which the loan/investment runs

Rate	The Rate of interest on the loan or investment - notice that this rate must apply to the same length of time that Periods is specified in. If Period is 12 months, then interest must be rate per month.

Payments	The periodic payments made or received

A payment made out is a negative value, for example -800 is 800 paid out by you, whereas 8000 is 8000 received by you.

Frame Style

The parameters required at each inlets are labeled on the object themselves. On the left are the inlets, on the right are the outlets.

Notice that the 5 parameters can either be input one by one, or they can be input as a 2 dimensional array into the Full Input inlet. If the full inlet and the individual inlets are both connected, then the individual inlets overrule the corresponding part of the full input. This is particularly useful when using the Solution Search object to change one of the parameters into this object, you can link it straight into the appropriate individual inlet.

Full Input

The full input accepts a two dimensional array with the parameters in the same order as listed on the individual inlets.

Here the table is horizontal, Future Value (FV) isn't known so its been left blank. Periods is implied by the width of the table, it is assumed to be 6 periods.

Notice that payments vary so 6 different values have been entered, if they remained the same only one would have been entered - this is the case for the Rate of Interest (Rate) which doesn't vary so only a single number 0.0075 has been entered.

This table also has headings, the Savings and Loans object will strip off these headings.

This has all the same values as the previous example, except that it is vertical. There are some occasions when CleanSheet cannot tell if the table is vertical or horizontal. This occurs when the table is roughly 4 or 5 parameters by 4 or 5 parameters. When this happens the table is assumed to be vertical.

Individual Inlet for Present Value, Future Value and Number of Periods

These parameters must be single numbers. If you provide an array into these inlets, then the first value in that array is taken.

Individual Inlets for Rates and Payments

These parameters are either single numbers, for when they are constant or arrays of numbers for when they vary. When you provide an array into these inlets, its size implies the number of periods over which the calculation is to run.

Individual Outlets for Present Value, Future Value and Number of Periods

These outlets always carry single numbers (strictly speaking double precision numeric objects - see data types).

Individual Outlets for Payments and Rates

These outlets always carry a 1 dimensional array of results, with one element for each period. Even if they do not vary, you will still get a 1 dimensional array from these outlets.

Full Outlet

This carries a complete table containing all the values calculated by the SAL function. Headings are appended to the columns and rows of the table.

For an example of the results from this outlet, see example sheet Sal1.cln.

Usage Example

The examples Sal1.cln and Sal2.cln contain examples of this object in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

Comparison with Traditional Spreadsheets

It is not very easy to do amortization tables on a traditional spreadsheet. Everything works fine until the number of periods vary, then you have to extend or shorten the table - which is manual operation - or program macros to build the table. On CleanSheet the equivalent to programming a macro would be to write a Computer Object program, however as amortization calculations are so common, they warrant an object to themselves.


Toolbox (General) Object
 Toolbox - General

Introduction

The general toolbox object contains a range of array manipulation functions. All of the functions relate to single arrays and hence this object takes a single input. The available operations are covered in General Toolbox Functions Listed.

Along with the main functions themselves, Toolbox objects offer a great deal of pre- and post-processing of the arrays to handle things such as headers and tranpose data. These are covered step-by-step in the General Toolbox dialogue.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time.

There are 4 outlets which can have any number of pipes connected to them.

Usage Example

The example Loaded.cln contains a General Toolbox object.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 General Toolbox	Selects which function from the General Toolbox list.


Toolbox (Financial) Object
 Toolbox - Financial

Introduction

The Financial toolbox contains the CleanSheet functions relating to finance and asset depreciation. The reason for choosing  one of these objects rather than a Calculator Object is because this object offers a great deal of pre- and post-processing which simplifies a sheet.

The full list of functions available with this toolbox is covered in the topic Financial Toolbox Functions Listed.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time.

There are 4 outlets which can have any number of pipes connected to them.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Financial Toolbox	Selects the function to use


Toolbox (Statistical) Object
Toolbox - Statistical

Introduction

The Statistical toolbox contains the CleanSheet functions such as Sum, Mean, Median and other statistical functions. The reason for choosing  one of these objects rather than a Calculator Object is because this object offers a great deal of pre- and post-processing which simplifies a sheet.

The full list of functions available with this toolbox is covered in the topic Statistical Toolbox Functions Listed.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time.

There are 4 outlets which can have any number of pipes connected to them.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Statistical Toolbox	Selects the function to use


Text Box Input Object
 Text Box (Input)

Introduction

When you want to input text into a sheet, you can either use an object input box, but this requires you to surround the text in double quotes in order to declare it as a string object (see data types), or you can use a Text Box.

The Text Box inputs a string object containing the text entered in it. The text is assumed to be a string, so there is no need to use double quotes.

You can also place these text boxes around a sheet as explanatory text, they do not need to be piped in.

Frame Style

The frame has 4 outlets, to allow pipes to be taken off in 4 directions.

Any number of pipes can be taken off the frame.

Entering Text into a Text Box

You must be in Use Mode.

Click (or double click) to select the box

The text to edit will be displayed in the edit field at the top of the window

Click and edit the text there

Click on the Tick to accept the text.

Notice that you cannot press Return to accept the text because this object can accept Return as part of the Text.

Resizing the Object

To resize the box, you must be in Edit Mode.

As you move the mouse over the edges of the frame, the cursor will change shape, at these points you can resize in the directions indicates by the arrows.

Clipboard Usage

To Copy the text to the clipboard, follow the same steps as though you were editing, then select all of the text and select copy to place it in the clipboard.

When you are editing text in the edit field at the top of the main window, Cut, Copy Paste and Clear all operate on the text you are editing.

Keyboard controls

When the Text Box is selected in Use Mode, typing anything will delete the text in the text box and start afresh with new text. You can cancel this by clicking on the Cancel button to reject it.

Usage Example

The file Lookup2.cln contains an example of this object in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Font Selection	Selects the typeface style, colour and size

 Colour Selection	Select the fill colour of the cells

 Contents Alignment	Set the alignment of the block of text


The cancel button rejects any changes you have made in the edited text and leaves the old text or data intact.


 Object Input Box

Introduction

The Object Input box inputs data items (see data types) using CleanSheet's array and object notation.

Contrast this with the Input Table object, the input table always inputs a two dimensional array into the sheet, while the Object Input Box can input single items.

For example consider the number 100 entered into an Input Table and an Object Input Box.

The Input table produces an array with one column and one row containing the number 100, while the Object Input box produces a single number.

Frame Style

The frame has 4 outlets, to allow pipes to be taken off in 4 directions.

Any number of pipes can be taken off the frame.

Entering Data into an Object Input Box

You must be in Use Mode.

Click (or double click) to select the box

The text to edit will be displayed in the edit field at the top of the window

Click and edit the text there, data is entered using CleanSheet notation, see Entering Data.

Click on the Tick to accept the text or press Return.

Resizing the Object

To resize the box, you must be in Edit Mode.

As you move the mouse over the edges of the frame, the cursor will change shape, at these points you can resize in the directions indicates by the arrows.

Clipboard Usage

When you are editing text in the edit field at the top of the main window, Cut, Copy Paste and Clear all operate on the text you are editing.

Keyboard controls

When the Object Input Box is selected in Use Mode, typing anything will delete the text in the box and start afresh with new text. You can cancel this by clicking on the Cancel button to reject it.

Usage Example

The file Sal2.cln contains an example of this object in use.

Consistent

In the case of the Input Object, a consistent object is one where, no matter how many times the expression you entered in this object is evaluated, it produces the same result.

When CleanSheet evaluates a sheet, if a pipe comes from a Consistent object and the object hasn't been edited or changed, then the pipe won't have changed and hence CleanSheet will not recalculate the pipe. This system is called Sparse Recalculation and it speeds up the calculating of a sheet.

If the expression you enter into an Object Input Box is likely to change, for example Now+10 would change because Now is a function returning the current time, then the object is inconsistent.

To select Consistent, switch to Use Mode and select it on the object menu. The default is a consistent object (indicated by a tick), no tick means inconsistent.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Font Selection	Selects the typeface style, colour and size

 Colour Selection	Select the fill colour of the cells

 Contents Alignment	Set the alignment of the displayed text.


Array Dissector Object
 Array Dissector

Introduction

The Array Dissector extracts sections from an input array and can process them to produce lower level arrays or individual objects. For example, it can extract column 2 from an array and return it as a 1 dimensional array.

The Array Dissector can produce up to 36 fragments from a single array - each fragment defined independently of the others.

The input array is assumed to be two dimensional, one dimensional arrays are treated as a single row.

One array goes in, multiple fragments come out.

The result is either 2 dimensional, 1 dimensional or just a single data object (see data types).

This is a key object within CleanSheet, other array dissections and extraction object are special cases of this used for specific purposes.

All of the features of this object are controlled by the Dissector Output dialogue,.

Frame Style

The number of outlets is definable, in this example frame we have 3.

The outlets are along the left and right edges of the frame, the inlets are top and bottom. Only one of these two inlets can be connected at once.

Usage Example

An explanatory example covering this object is contained in Dissect.cln. A more typical example is provided in Lookup1.cln.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Dissector Outputs	Sets the fragments to dissect out


 Calculator Object

Introduction

The Calculator object evaluates a single equation to produce a single result. It can have up to 26 inputs into the object, these are assigned to the variables a,b,c....z, you can then refer to these variables in the equation.

A typical equation looks like this A*B+C this multiplies input A by input B and adds input C. The equation is not case sensitive, a*b+c is identical.

The equation is evaluated each time a result from the Calculator is required.

The inputs may be arrays, a+b may add a to b, but it may equally add corresponding elements of arrays a and b to produce a result array.

See the topic General Functions for a list of available functions.

Frame Style

The inlets are either side of the frame, only one inlet A can be connected and one inlet B... and so on, the reason there are two of each inlet type is simply to make it easier to plumb this object in.

This example shows 6 inlets, the frame expands to allow for more inlets.

The outlets are top and bottoms, they carry the result of the equation - any number of pipes can be taken off these.

Array Manipulation with Calculator Objects

The full range of array manipulation functions are available within the Calculator, so it is a simple matter to use the array notation to split or join arrays. For example:

{A[0],B[1]}	This produces a two elements array with element 0 as the first column of A and the second element is column 1 of B.

{{A}}	This produces a two dimensional array (notice the double curly brackets). If A was the number 10, the result would be the two dimensional result {{10}}.

Other array manipulation functions are available within CleanSheet, see Array Manipulation Functions.

Usage Example

The files Database.cln, Loaded.Cln and Sal2.cln contain examples of this object in use.

Consistent

A Calculator object is consistent if the equation it contains produces the same result for the same inputs.

When CleanSheet evaluates a sheet, if a pipe comes from a Consistent object and the object's inputs haven't changed, then the pipe won't have changed and hence CleanSheet will not recalculate the pipe. This system is called Sparse Recalculation and it speeds up the calculating of a sheet.

An inconsistent equation is one that includes some unpredictable element, such as the Rand function, the Now function and similar functions that give different result each time they are evaluated.

To select Consistent, switch to Use Mode and select it on the object menu. The default is a consistent object (indicated by a tick), no tick means inconsistent.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Number of Inputs	Sets the number of inputs

Special Notes

When constructing an array which is a composite of many calculations, or when preparing an array which involves repeating the same calculation over and over again, a special object called a COG object is available.

In cases where even the Cog object isn't flexible enough, a Reporter /Announcer pair may be used.

When the Report/Announcer object proves unsuitable, a Computer Object is available.

Comparison with Traditional Spreadsheets

This object is equivalent to a single calculation in a single cell of a spreadsheet, but with the important difference that CleanSheet is object oriented and hence most of its operations can be performed on arrays. This means that quite often you will find a Calculator object is sufficient to replace a whole column of equations and when it isn't, rather than use a whole array of calculator objects, it is usually more appropriate to use other CleanSheet objects.

You may be use to entering an = sign at the start to indicate an equation. You should not do this with CleanSheet.


Number of Inputs

This dialogue simply sets the number of inlets into the object.


 Announcer Object

Introduction

The Announcer object works in conjunction with the Reporter Object. The pair are used where a single calculation is to be applied over and over again to parts of a table. The Announcer Object sends the table row-by-row or column-by-column into a calculation and the Reporter then gathers the results, row-by-row or column-by-column. The two objects talk to each other so that when the Announcer has finished sending, the Reporter stops collecting.

Announcer/Reporter objects can be nested to handle all elements of a two dimensional array.

See Also, Announcer/Report - How they work. and Reporter Object.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time. The Announcer expects a two dimensional array as Input, if a 1 dimensional array is received it is treated as a single row from a two dimensional array.

There are 4 outlets which can have any number of pipes connected to them.

Usage Example

The files Database.cln, Sal2.cln and Switch.cln contain examples of Reporter Announcer objects in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Announcer Type	Set row-by-row or column-by-column announcing

Special Notes

If the entire calculation you are to perform can be defined by one of more equations (as opposed to one or more CleanSheet objects), then the Cog Object may be more appropriate. This can perform repeated tasks on sections of two dimensional arrays, but only provided the processing is simple enough to be defined by an equation.

If all you want is to add corresponding numbers from two tables, or a similar trivial calculation, remember that equation a+b can adds corresponding elements of arrays, a simple Calculator Object may be all you need.


 Reporter Object

Introduction

The Reporter object works in conjunction with the Announcer Object. The pair are used where a single calculation is to be applied over and over again to the parts of a table. The Announcer Object sends the table row-by-row or column-by-column into a calculation and the Reporter then gathers the results, row-by-row or column-by-column. The two objects talk to each other so that when the Announcer has finished sending, the Reporter stops collecting.

Announcer/Reporter objects can be nested to handle all the elements of a two dimensional array.

See Also, Announcer/Report - How they work. and Announcer Object.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time. The Reporter expects a one dimensional array as Input which it assembles into a two dimensional array. However, two dimensional arrays will be assembled into three dimensional arrays, 3 into 4 and so on. In other words the output is a higher dimension of array than the input.

There are 4 outlets which can have any number of pipes connected to them.

Usage Example

The files Database.cln, Sal2.cln and Switch.cln contain examples of Reporter Announcer objects in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Reporter Type	Set row-by-row or column-by-column reporting

Special Notes

If the entire calculation you are to perform can be defined by one of more equations (as opposed to one or more CleanSheet objects), then the Cog Object may be more appropriate. This can perform repeated tasks on sections of two dimensional arrays, but only provided the processing is simple enough to be defined by an equation.

If all you want is to add corresponding numbers from two tables, or a similar trivial calculation, remember that equation a+b can adds corresponding elements of arrays, a simple Calculator Object may be all you need.


Announcer/Report-How they work
How Announcer/Reporter Works

The Announcer Reporter object pair is used when the same calculation is to be performed repeatedly on parts of a table.

Consider the following example. The third element of each row is to be multiplied by the second element of each row.

The Announcer announces each row of the input table to the sheet.

The Calculation object constructs a 1 dimensional array with the third column multiplied by the second column.

The Reporter Object assembles these one dimensional arrays into a finished two dimensional result.

To see how this is evaluated, see the Reporter/Announcer Flip Book.

Nesting Reporter Announcer Objects

Reporter/Announcer Objects can be nested to process multiple dimensions of an array. There are acceptable and unacceptable ways of doing this.

This is acceptable, the row-by-row Announcer produces 1 dimensional arrays (row arrays) which the column-by-column Announcer chops into individual elements. The result is reassembled back into the same order.

At first glance, this may seem acceptable - but it isn't, the Column-by-Column Announcer returns a 1 dimensional array - a row array - which the row-by-row Announcer announces as a single row array.

The Announcers always return a 1 dimensional array which is a row array, even a column-by-column announcer returns a row array.

Surprisingly this will work equally as well as the first example. The column-by-column Announcer produces one dimensional row arrays. The next column-by-column Announcer chops these row arrays into elements for the calculation.

The Column-by-Column Reporter then assembles these elements into the next higher dimension (a 1 dimensional row array) and finally the last Reporter Object assembles these 1 dimensional rows, into a 2 dimensional table.

Multiple Announcers, Single Reporter

A calculation may need several parameters from several different sources. Under those circumstances several Announcers may be needed driving one Reporter.

This is a perfectly acceptable arrangement of Announcers and Reporters.

Multiple Reporters, Single Announcer

There may be times when you need to obtain two sets of results from a calculation such as the example below. This is not allowed within CleanSheet because the Reporter is actually the object that drives the Reporter/Announcer pair, and it is not possible to have two Reporter Objects driving the calculation at the same time.

A correct approach to a problem like this is to open out the calculation into 2 separate Announcer/Report pairs.


This is an Input Table object, used to input a two dimensional table into the sheet.


This is an Announcer Object, it announces the table, row-by-row to the calculator object.


This is a Calculator Object, it contains the equation {A[0],A[1],A[2]*A[1]}.

A[0]	Is element 0.

A[1]	Is element 1

A[2]*A[1]	Is element 2 * element 1

{... , ... , ...}	Assembles the result into a 1 dimensional array


This is a Reporter Object, it re-assembles the 1 dimensional arrays into a final two dimensional array.


This is an Output Table object, use to display the finished array.


 Transpose Object

Introduction

The Transpose object, takes an input two dimensional array and transposes the first two dimensions. Columns become rows and rows become columns.

Frame Style

The frame has 4 inlets, only one of which can be connected at any one time.

There are 4 outlets which can have any number of pipes connected to them.

Usage Example

An example of the action of the Transpose object is shown below.

Notice that Transpose applied to a 1 dimensional array such as {1,2,3,4} returns a 2 dimensional column array {{1,2,3,4}}.

Dialogues supported

 Object Attributes	Sets the object's tags and name


 Chi-Square Object

Introduction

The Chi-Square object is a statistical hypothesis test. It has two forms, one which tests the goodness of fit for a curve to a set of points, and the other which compare a predicted result with an observed result to test how well the two match.

The result of this test is a number in the range 0 to 1 where 0 is a perfect match and 1 is a total mismatch.

Frame Style

The frame has 4 outlets that are all the same, any number of pipes can be taken off these outlets.

There are two different types of inlet, Inlets A and B,

A	Is the Observed Data

B	Is the Expected Data

Hypothesis Testing

When testing a hypothesis, the input is two arrays the same size.

The Observed Data is the array of the results actually observed.

The Expected Data is the array of results that our hypothesis predicted

Curve Fit Testing

The Observed Data is a two dimensional array of XY points on the curve. The array can either be of the form {{x1,y1}, {x2,y2}, {x3,y3}....} or of the form {{x1,x2,x3...}, {y1,y2,y3...}}

The Expected Data is an equation specified as a function of x that describes the curve.

Usage Example

The file Xyscat.cln contains an example of this object in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

Background Information

This is the object level implementation of the ChiTest function. The reason it has been promoted to object level is because it is such a common test when applied to empirical functions approximated with the Curve Fit object.


 Overlay Object

Introduction

The Overlay object lays one input over another, over another, to form a resultant two dimensional array. Up to 36 inputs can be overlaid, several inputs go in, one result array comes out.

Which part of the result array is overlaid by each input is determined by the Overlay Settings dialogue, you should familiarise yourself with this dialogue before trying to use the Overlay object.

Frame Style

The inlets are either side of the frame, only one inlet A can be connected and one inlet B... and so on, the reason there are two of each inlet type is simply to make it easier to plumb this object in.

This example shows 6 inlets, the frame expands vertically to allow for more.

The outlets are top and bottoms, they carry the finished overlaid array - any number of pipes can be taken off these outlets.

Usage Example

The file Lookup1.cln contains an example including an Overlay Object.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Overlay Settings	Sets where each input is overlaid


 Computer Object

Introduction

The Computer object runs a program in CleanSheet's Cesk programming language. It has up to 26 inlets, labeled A.. to Z from which it assigns the value to corresponding variables A to Z and then runs the main{} function within the Computer Object.

The program then executes, using the supplied variables and when it's finished, it uses the Return command to terminate the program and return a result. This result is the output of the Computer Object.

The programming language is explained in the topic Cesk Programming Language Introduction.

Frame Style

The inlets are either side of the frame, only one inlet A can be connected and one inlet B... and so on, the reason there are two of each inlet type is simply to make it easier to plumb this object in. Not surprisingly the data coming into inlet A is assigned to variable A, inlet B to Variable B and so on.

This example shows 6 inlets, the frame expands vertically to allow for more.

The outlets are top and bottoms, they carry the finished overlaid array - any number of pipes can be taken off these outlets.

Editing the Program

Select Program from the Object menu or double click on the Computer object. The text editor window will open allowing you to edit the program. You can open as many text editor windows as you have computer objects, one text editor window per object.

Debugging a Computer Object

Leave the text editor window open with the program displayed.

Run the sheet by either Clicking on Manual Recalculation or if you have automatic recalculation switched on, change an input object to cause a recalculation.

When the Computer object executes its window will be topped and the line being executed will be highlighted.

The Inspect Variables Dialogue will appear which allows you to set the speed of execution and examine the variables within the program.

If you have several Computer Objects on screen, you may wish to trace several of them. To do this simply leave text edit windows open for several of the computer objects. As each object is recalculated, its text edit window will be topped and the Inspect Variables dialogue will appear for each of them in tern.

Usage Example

The files Computer.cln, Loaded.cln and Spiral.cln contain examples of the Computer Object.

Consistent

A Computer object is consistent if the program it contains produces the same result for the same inputs.

When CleanSheet evaluates a sheet, if a pipe comes from a Consistent object and the object's inputs haven't changed, then the pipe won't have changed and hence CleanSheet will not recalculate the pipe. This system is called Sparse Recalculation and it speeds up the calculating of a sheet.

To select Consistent, switch to Use Mode and select it on the object menu. The default is a consistent object (indicated by a tick), no tick means inconsistent.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Number of Inputs	Sets the number of inlet points

 Program	Opens the Program Editor

Special Notes

The Cesk Programming language is very similar to C, but not quite. If you are familiar with C, spend a few moments reading the Programming Language Introduction to familiarise yourself with the differences.

An extremely common mistake is to write a program, recalculate the sheet and wonder why the program isn't running. If you have no output pipes connected to an object then there is no reason for CleanSheet to calculate a result for that object. This means that to run a computer program you must have the output from the Computer object connected to something.

Certain variables are reserved by CleanSheet. (This is because CleanSheet uses Cesk data structures to store the sheet in). The list relevant to the Computer object is:
ls_g which holds the tokenised program and the number of inputs into the object.
l_a used as a temporary,
gs_p reserved for sheet data
w_p stored data
w_l stored data
w_a stored data
gs_l stored global data
Do not assign anything to these variables within a Computer Object.

Comparison with Traditional Spreadsheets

The Macros in a Spreadsheet are two separate features loosely linked into one. One part of macros is the recording of keystrokes and mouse movements, and the other part is the programming of basic sheet operations such as Print and Amortization tables.

For Recording and Replaying keystrokes and mouse movement, use the Windows Recorder Utility.

For basic operations such as amortization tables and printing of sheets use the appropriate CleanSheet object.

For the programming of custom problems that do not fit easily in CleanSheets object structure, use the Computer Object.


This dialogue simply sets the number of inlets into this Computer Object, the maximum is 26 because they are assign to the variables A to Z.


Editing a Program

Introduction

The program editor is a basic text editor with some additional features to help you check your programs.

It has a number of features, all selectable from the menus.

File - Print

This prints the program to the default Windows printer in the default typeface for that printer.

File - Update

When you have made changes to a program and you want to Update the Computer object that contains the program, select this options.

File - Exit and Update

Closes the editor window and if the program has been edited, it asks if the Computer object is to be updated aswell.

Edit - Undo

Undoes the last change you made to the text.

Edit -  Cut

Cuts the selected portion of text out and places it in the clipboard.

Edit - Copy

Copies the selected portion of text to the clipboard.

Edit - Paste

Pastes the text in the clipboard to the cursor position, if any section of the text is selected then that section is overwritten.

Edit - Clear

Deletes any selected text without affecting the clipboard.

Edit - Find

Searches for matching text (See Find).

Edit - Check Brackets

Checks the program to see if there are any incorrect brackets. Brackets can be the most difficult thing to get correct within a complex program and this option is a useful way of finding any problems.

If an area of text is selected, it check the brackets in that area only

If no text is selected, it checks the whole of the program

If this options detects an unexpected bracket it highlights it. If there are an unbalanced number of brackets, but CleanSheet is unable to identify where, it displays an Unbalanced Brackets Error and shows which type of brackets and how many.

For example: (0) {1} [0] means one too many opening curly brackets.

Edit - Paste Function

Pastes a CleanSheet function into the text. This dialogue is described in the Paste Function Topic.


Solution Search Object
 Solution Search

Introduction

Solution Search, changes values in a sheet until it reaches an optimum solution - in other words is searches for a solution.

There are 3 sections to a Solution Search problem:

The Sheet to Optimise, you must design a sheet that calculates the value that Solution Search is to find an optimal solution for. You must also tell Solution Search what type of optimum to look for - a maximum? a minimum? or maybe some particular value.

The Constraints, you must design a section of the sheet to calculate any constraining results (for example this value must not exceed 100 for a valid solution), feed these values into the constraints section and tell Solution Search how they are constrained.

The Outputs, what can Solution Search change to find a result?

Frame Style

The frame has the constraints along the left side and the outputs along the right. In the example below there are 3 inlets for the constraints and 2 outlets for the outputs, there can be up to 26 inlets and 26 outlets, to accommodate them, the frame expands.

The optimal value that Solution Search is looking for is fed into the Optimum inlet, either the top or bottom inlet - they are both the same.

The Solution to Find

The Solution Search object optimises the input fed into its 'optimum inlet' the inlet top and bottom of the frame. It can aim for 3 things, the minimum result, the maximum result and a result closest to a particular value - this is set by the Solution to Find dialogue.

Constraints

The constraint inlets are not the constraining rules themselves. Instead they are values that are used in the constraining rules.

For example if inlet A is the array {10,20,30,40} and inlet B is {20,30,40,50}, we might have a Constraint rule that says  A+B <= {90,90,90,90} CleanSheet would then evaluate Inlet A plus Inlet B to get {30,50,70,90}, and then compare it against {90,90,90,90} to see if it is less than or equal. In this case corresponding elements are checked since the two arrays being compared are the same type. This constraint is TRUE, so the solution that caused these values is a valid one.

The constraint rules are set on the Constraints dialogue.

Outputs to Vary

The Outputs to Vary dialogue sets two things, it sets the initial values of the outputs and it sets the types of outputs. For example, you want outlet A to be a column array with 4 numbers in it. The initial value of output A would be {{0,0,0,0}} , notice the two sets of curly brackets indicating a column array. Here the Solution Search object will vary those 4 values in its attempt to find an optimum solution.

Another possible example is that you want output B to be a complex number. Here you might enter 3+4i in the initial value for B. CleanSheet would change both parts of the complex number in its search for the optimum solution.

Solving the Sheet

To solve the sheet, switch to Use Mode and click in the centre of the Solution Search object. This starts the solution search.

When the sheet is recalculated, Solution Search has the last optimal solution it found as its output. This means that you can have several Solution Search objects on the sheet, you can solve the ones you want by clicking on them, then recalculate the whole sheet with the new optimum values.

Recalculating the sheet does not start a Solution Search.

Usage Example

The file Linear.Cln contains an example of a linear sheet. The file Optimum.cln contains examples of non-linear constrained and unconstrained optimisation.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Outputs to Vary	Sets the initial output values and types

 Constraints	Sets the constraints within which to work

 Solution to Find	Find minimum, maximum, or specific values

Comparison with Traditional Spreadsheets

There are two features on a traditional spreadsheet that are branches of optimisation - Goal Seeking and the Solver. The separation is due to history, Solvers are very difficult thing to write, but it is very easy to write a simplified 1 variable Solver, which is exactly what a Goal Seeker is. When you need either of these features, you should be using the Solution Search object.

Background Information

There are 3 basic techniques Solution Search uses to find an optimal solution.

Linear Programming (LP for short)

Davidon Fletcher Powell unconstrained optimisation (DFP for short)

Constraining boundary traversal

LP is a well understood form of mathematics, Solution Search checks if the sheet is linear in its behaviour and if it is, uses an LP algorithm to find a solution. If a solution exists LP will nearly always find it.

DFP is also a well understood approach, but in non-linear equations it may not find the best solution. Consider a function of two variables that describes a flat surface. Now imagine that surface full of potholes going off to infinity in all directions. How can you know if you've found the deepest pothole without checking an infinite number to see? If the sheet is not linear, and the result seems unreasonable, change the start values in the Outputs to Vary dialogue and restart - it may find a better solution.

Constraining Boundary Traversal, is the final system used. When the minimum found by the DFP algorithm is out of bounds, this algorithm traverses along one or more offending boundaries until it finds a point as near to the boundary as it can. The theory being that, if the real minimum is outside the acceptable limits, then the optimal solution must lie on the boundary.

As you can see, CleanSheet uses the techniques in decreasing order of likely success.

For further reference:

Numerical Methods for Constrained Optimisation, Gill and Murray, ISBN 0-12-283550-6, Academic Press.

Quantitative Techniques, T Lucey, ISBN 1-873981-26-0, DP Publications Ltd.


Sum Product Object
 Sum Product

Introduction

The Sum Product object, performs two operations in one go, first it performs a Product (a multiplication along the rows or columns) then it sums along the rows or columns.

This is such a common calculation that it is implemented at object level.

The available options for this object are covered in the topic for the Sum Product dialogue.

Frame Style

The frame has 4 outlets that are all the same, any number of pipes can be taken off these outlets.

There are two different types of inlet, Inlets A and B, these correspond the inputs A and B on the Sum Product dialogue.

Usage Example

The file Linear.cln contains examples of the Sum Product object in use.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Sum Product Type	Set what to multiply and what to sum


 Product

Introduction

The Product object multiplies two 2 dimensional arrays together to produce a resulting 2 dimensional array.

The options available when calculating the Product of two arrays is discussed in the topic Product dialogue.

Frame Style

The frame has 4 outlets that are all the same, any number of pipes can be taken off these outlets.

There are two different types of inlet, Inlets A and B, these correspond the inputs A and B on the Product dialogue.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Product Type	Set how to multiply the two arrays


Button Group Object
 Button Group

Introduction

The Button group is an input object that selects from several predefined values. It is used where a limited number of input states are possible, each button corresponds to one state.

There are 3 types of button group:

The commonest type is the Radio group, in groups of this type only one button can be selected, and the value returned by the group is the value assigned to the selected button.

Another type is the list of buttons, in these groups every button can either be selected or not selected. Each button has a different value according to whether it is down or up, and the return from the group is a 1 dimensional array of the button values.

The third type of button group is a grid of buttons, any number of buttons can be selected and each button has a different value depending on whether it is up or down. The return is a two dimensional array, with the buttons in their corresponding rows and columns. For example a grid of buttons 4 across and 2 down produces an array 4 columns by 2 rows.

The type of group and the number of buttons is determined by the Button Group Style dialogue.

Frame Style

The frame has 4 outlets, to allow pipes to be taken off in 4 directions.

Any number of pipes can be taken off the frame.

Keyboard controls

Each button in a group can be assigned a keyboard character A through Z. This is set by the Button Data dialogue.

To select a button using its keyboard shortcut:

You must be in Use Mode

Select the Button group object by pressing Tab until its frame is highlighted.

Press the letter on the keyboard without Control or Alternate.

Usage Example

The file Button.cln contains an example of a Button Group Object.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Button Group Style	Sets the type of button group and number of buttons

 Button Data	Sets the value assigned to each button


 The Tab key sometimes looks like this.


Slider Input Object
 Slider Input

Introduction

The Slider is an input object used to put a single value into a sheet. It has the following properties:

It is interactive, using either the mouse or keyboard

Its design gives it a natural upper and lower limit

It can output differing data types, not just numbers

The upper and lower limits are definable

You should consider these properties when deciding if it is suitable. If you want all of the properties except for the upper and lower limit, then use a Tumbler Object instead.

For example, if you wanted to try out different retail prices in a model and you knew the price must be between certain limits, then you could use this object - it would be a lot easier than typing and adjusting numbers.

Frame Style

The frame has 4 outlets, to allow pipes to be taken off in 4 directions.

Any number of pipes can be taken off the frame.

Resizing the Slider Object

Switch to Edit Mode

Move over the Slider, as you pass over the resizing zones, the cursor will change shape.

Click and draw out the slider to its new shape.

If the Slider is longer than it is high, then it becomes a horizontal slider.

Changing the Slider with the Mouse

To move the thumb of a Slider, you must be in Use Mode.

Click and drag the thumb with the mouse

Alternatively, click above/left of the thumb to decrease the slider

Click below/right to increase the slider.

Keyboard controls

The keyboard controls work in Use Mode.

Increase the value by 5% of the difference between its limits

Increase the value by 5%

Decrease the value by 5%

Decrease the value by 5%

 	Move the slider to its minimum value

 	Move the slider to its maximum value

Usage Example

The file Spiral.cln contains an example of the Slider Object.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Number Format	Controls how numbers are displayed

 Date Format	Controls how dates are displayed

 Time Format	Controls how times are displayed

 Complex Format	Controls how complex numbers are displayed

 Font Selection	Selects the typeface style, colour and size

 Slider Options	Set the limits and style of the slider.


This is the display showing the current value of the Slider.


This is the minimum value of the slider


This is the maximum value of the slider


This is the Thumb of the slider - this can be dragged with the mouse to change the Sliders value.


Click here to decrease the sliders value.


Click here to increase the sliders value.


 XY Scatter Graph

Introduction

The XY Scatter graph plots XY Cartesian coordinate pairs. Each group of coordinates is called a data series, this graph supports up to 8 series displayed simultaneously.

Frame Style

The frame has two main entry points. The Full Inlet requires a two dimensional array, this array is interpreted by the graph into several data series. The Separate Series inlets, allow one series per-inlet.

You cannot connect both the Full Inlet and the Separate Series inlets at the same time.

Full Inlet

The full inlet expects a two dimensional array, if it detects column headings it will remove them and use them as series names.

If you include titles in the table they must be string objects (See Data Types). Notice in the above example that the X's only appear once. The first column is taken to be the X ordinates and the next 3 columns are the Y ordinates plotted against the corresponding X.

For example series 'S2' has the 3 points in it, {X 100, Y 40} {X 150,Y 50} and {X 200, Y 10}.

In this example, the column headings for "S1" to "S3" are taken by the graph and used as the series names.

This example produces exactly the same data points as the previous example. The difference is the omission of the column headings.

Separate Series Inlets

These inputs allow data series to be input, series by series. Each Inlet 'A' to 'H' corresponds to the plotted series 'A' to 'H'.

This gives you much finer control over the plotted data. For example the Full Inlet has only one set of X ordinates to plot against, while the separate series Inlets plot against several sets of X ordinates.

These inputs require 2 columns of data, the first column is the Xs and the second columns is the Y's. The above table corresponds to 3 points {X 100, Y 70}, {X 150,Y 40}, {X 200, Y 20}.

Headings are not allowed for these inputs.

Plotting Equations onto an XY Scatter Graph

The XY Graph can recognise when equations are being fed into it. It can also use string objects which are easier to enter into CleanSheet. The equations are plotted against the values along the X axis.

For example the string object "10*x+20" will plot as a straight line.

The function is always be a function of x.

When the X axis is scaled automatically, CleanSheet will have problems deciding how to scale the plotted graph. There are 2 ways around this, the first is to use manual scaling so that CleanSheet has a range of X values to plot against, the alternative is to have some real data points going into the graph. CleanSheet will scale against those data points and plot the equation against the same X scale.

The file XyScat.Cln contains a sample XY Scatter Graph.

The Components of the Graph

The graph consists of four separate parts, the main part is the plot area, this section is where the data series are drawn. The index box shows a key linking the series to its name, the Title Box displays the title of the whole graph.

The background is drawn behind the other sections of the graph.

Resizing the Components

Switch to Use Mode.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized to enclose the components of the graph

Clipboard Usage

When in Use Mode, the graph can be copied as a picture to the clipboard and a picture can be pasted into the background of the graph.

Usage Example

The file XYScat.cln contains a sample XY Scatter Graph and the file Xyscat3.cln contains some sample graph styles. The file XYscat2.cln contains a example of using CleanSheet in non-spreadsheet applications.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Number Format	Controls how numbers are displayed

 Background	Sets the style of the background

 Grid Style	Sets the style and spacing of the grid

 Axis and Grid	Set the style of grid and axis text

 Title	Sets the text and style of the title

 Index Box	Sets the style of the Index Box

 XY Series Options	Set the style of each data series

 X Axis Scale	Sets the scaling of the X axis

 Y Axis Scale	Sets the scaling of the Y axis

Special Notes

To Create a logarithmic version of this graph, select the Logarithmic Scaling option on the X and/or Y Axis Scaling dialogues.


 XY Scatter Input

Introduction

The XY Scatter Input object inputs an XY coordinate pair into a sheet. The coordinate pair consists of a 1 dimensional array of 2 numbers {x,y}.

This is the input version of the XY Scatter Graph, and has the following properties:

The point is placed graphically with the mouse

Two values are input at once, this is an important property - if you input 2 values separately and you are in automatic recalculation mode, the sheet will be recalculated after changing one of the values, leading to needless recalculation and spurious figure in any files produced by Filing Clerk objects on the sheet.

You can see the relationship between the two ordinates.

If you want to place a point on a map, you can paste a map into the background and use this object to retrieve the coordinates.

If you want to allow only certain combinations of X and Y, you can paste a picture into the background, indicating which areas of the graph are valid, it would then be clear when placing a point, where the point is allowed and where it isn't.

Frame Style

The frame has 4 outlets, to allow pipes to be taken off in 4 directions.

Any number of pipes can be taken off the frame.

The Components of the Graph

The graph consists of several separate parts. The main part is the plot area, this is the area in which you place a point. The Title Box contains the title of the graph. The background is drawn behind the other parts of the graph.

Resizing the Components

Switch to Use Mode.

Select Move and Resize the Graph Components on the Graph Paint Mode dialogue.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized to enclose the components of the graph

Plotting the Input Point

Switch to Use Mode

Set the Graph Paint Mode to Paint the Data

It is advisable to set the Scale of the Graph.

Click with the mouse on the Plot Area, the point will be drawn.

Clipboard Usage

When in Use Mode, the graph can be copied as a picture to the clipboard and a picture can be pasted into the background of the graph.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Number Format	Controls how numbers are displayed

 Background	Sets the style of the background

 Grid Style	Sets the style and spacing of the grid

 Axis and Grid	Set the style of grid and axis text

 Title	Sets the text and style of the title

 X Axis Scale	Sets the scaling of the X axis

 Y Axis Scale	Sets the scaling of the Y axis

 Graph Paint Mode Set painting or sizing of graph components


XY Scatter Calculation
 XY Scatter (Calculation)

Introduction

When you have a curve on a graph that represents a function, and you want to imitate that function within a spreadsheet, this object allows you to trace or enter that curve and use it directly as a function within your sheet.

An X value fed into the graph is mapped onto the curve and the Y value for that point is read off and returned as the output.

For a fuller discussion see Empirical Functions

Frame Style

The frame has X and Y inputs as indicated below. Which input is connected determines the function that is performed, either X is converted to Y or Y is converted to X.

This object can actually do both conversion simultaneously, the Y Inlet is converted to its X ordinate and output through the X outlet and the X Inlet is converted to the Y ordinate on the curve and the result appears at the Y Outlets.

This means that 1 X and 1 Y inlet can be connected at any one time, and any number of pipes can be taken off the X and Y outlets.

The Components of the Graph

The graph consists of several separate parts. The main part is the plot area, this is the area into which the function is drawn. The Title Box contains the title of the graph. The background is drawn behind the other parts of the graph.

Resizing the Components

Switch to Use Mode.

Select Move and Resize the Graph Components on the Graph Paint Mode dialogue.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized to enclose the components of the graph

Painting the Function onto a Graph

Switch to Use Mode

Select Paint the Data on the Graph Paint Mode dialogue

Click with the mouse to place a point on the graph

The X ordinates are always kept sorted.

Clipboard Usage

When in Use Mode, the graph can be copied as a picture to the clipboard and a picture can be pasted into the background of the graph.

Conversion

An X value fed into the graph is converted to a Y value, there can only ever by one possible Y value that corresponds to an X because the X values are always kept sorted. Any X value for which there isn't a valid Y value is converted to a Null.

A Y value fed into the graph is converted to an X value, here the first valid X value is used, in the example below X1 is returned. Again if there are no valid X values, then a Null is returned.

When an array of numbers is fed in, then each number is converted separately and an array of exactly the same type is returned. For example {{10,20,30,40},10} could become {5,12,14,25},5}.

Usage Example

The file Emp1.cln contains an example of this graph.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Number Format	Controls how numbers are displayed

 Background	Sets the style of the background

 Grid Style	Sets the style and spacing of the grid

 Axis and Grid	Set the style of grid and axis text

 Title	Sets the text and style of the title

 X Axis Scale	Sets the scaling of the X axis

 Y Axis Scale	Sets the scaling of the Y axis

 Graph Paint Mode Set painting or sizing of graph components

 XY Scatter Points	Edit the XY Points by value


3D Graph Object
 3D Graph

Introduction

The 3 Dimensional graph is a 3 dimensional version of the Line/Column/Area Graph. It has most of the same features, but simply extended into 3 dimensions. It supports up to 8 data series displayed at the same time.

Graphs can be stacked onto each other.

Graphs can be layered, with each of data series at a different depth.

Graphs can be scaled as a percentage

There are 4 styles that the series can be displayed in, Columns (solid towers), Ribbons (thick strips of colour), Spheres at the points and Area (same as the 2 dimensional version, but with thickness added).

Frame Style

There can be up to 8 series overlaid on this graph object, each series can be piped in separately, or alternatively a two dimensional array can be put into the 'Full' inlet, this two dimensional array is broken down into separate series.

The interval names inlet is to input the names given to the horizontal intervals on the graph.

Individual Series Inlets

The inputs data for these is the data for one series only, the inlet you attach it to determines which series the data is for  - attached to inlet A and that is the data for Series A.

This graph object expects a 1 dimensional array of data into these inlets, however it can process two dimensional arrays to achieve the result it expects.

Full Inlet

The full inlet is used when all the series are in a two dimensional array. This array can contains interval headings, titles and so on - the graph object analyses the array and decides what is what.

When a title is identified it is used for the appropriate headings.

You cannot mix Series Inlets with the Full Inlet, one or the other can be connected, CleanSheet will not allow you to connect both.

The Components of the Graph

The graph consists of many separate parts, the main part is the plot area, this section is where the data series are drawn. The index box shows a key linking the series to its name, the Title Box displays the title of the whole graph, finally the background is drawn behind the rest.

Resizing the Components

Switch to Use Mode.

Click with the mouse on the part of the graph to resize

The section will be highlighted with a banding box.

Resize by the resize points, or move the component.

The frame will be resized automatically

Clipboard Usage

When the sheet is in Use Mode, the graph can be copied as a picture to the clipboard and a Picture can be pasted in for use as the background.

Usage Example

The examples Button.cln contains an example of this graph.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Number Format	Controls how numbers are displayed

 Background	Sets the style of the background

 Title	Sets the text and style of the title

 Index Box	Sets the style of the Index Box

 Y Axis Scaling	Set the scaling of the graph

 Pirouette	Spin the graph around

 3D Graph View	Set the rotation and perspective

 3D Axis and Grid	Set the style of the back planes, base, and axes

 3D Graph Options	Set the options for the 3D Graph

 3D Series Style	Set the style of each data series

Special Notes

3D Graphs have a fault inherently due to being drawn on 2D surfaces - the perspective distortion. See Perspective Problems.


How Cog Works

Example

Consider a simple example of a toy car manufacturer.

A is the number of cartons of each of our toy cars we have sold as a row matrix.

B is the cost of the materials plastic and steel that each type of toy car uses.

From these 2 we aim to calculate the cost of the materials we have used on each of our 4 types of toy car.

This can all be done with the equation:

Area Affected:	All

Equation:	A[dx][0] *  ( B[0][dx]  + B[1][dx] )

The Size of the result will be 1 row of 4 columns, but by setting the number of columns to 'Maximum Input Width'  instead, if we add more models to our range, we will not have to modify the Cog Object.

To see how this is evaluated, see the Cog Flip Book 1.

Example

Consider another example, Input A is an array of sales figures for year 1990 with headings on the array. Input B is another array of sales figures, for year 1991. We want to add the two sets of sales figures together, but we also want to keep the headings.

We can do this with 4 equations, one equation to do the adding, one to copy the column headings, one to copy the row headings, and finally one to set the top corner text to read "90/91"

Area Affected:	{1,1,Edge,Edge}

Equation:	A[dx+1][dy+1] + B[dx+1][dy+1]

Area Afffected	{1,0,Edge,0}

Equation	A[dx+1][0]

Area Affected	{0,1,0,Edge}

Equation	A[0][dy+1]

Area Affected	{0,0,0,0}

Equation	"90/91"

Notice that we have used 'Edge' rather than Column 3 or Row 3. Having defined it this way, if the arrays increase in size, this Cog object will still work.

To see how this is evaluated, see the Cog Flip Book 2

Notice that as you go through this flip book that dx and dy always start at 0,0 at the top left of the area covered by each equation. Even if the area affected by an equation is {1,1,edge,edge} when the Cog object is calculating the first element column 1, row 1 of the result it still assigns dx=0 and dy=0.


Colour Dialog
Colour

Introduction

This dialogue appears again and again throughout CleanSheet, it is the standard colour selection dialogue for Windows applications.

To select a colour, simply click on it with the mouse or use the Tab and Cursor keys to select a colour.

Selecting Non Standard Colours

If the colour you want is not included on this dialogue, select the 'Define Custom Colours' button, the dialogue will extend to reveal the colour mixing section.

Select a colour from the smear of colours.

Alternatively enter the colour as Red/Green/Blue intensities.

Alternatively enter the colour in terms of Hue/Saturation and Luminosity

Defining a Custom Colour

Select the Custom Colour you wish to change on the left of the dialogue.

Select the colour you want on the right of the dialogue.

Select 'Add to Custom Colours'

The 16 custom colours are stored by CleanSheet to disk, so they are available whenever you use CleanSheet.


This section contains a range of basic colours within the system.


This section contains colours you have defined.


This button allows you to select a custom colour, or redefine the colours in the Custom Colours section.


This section contains all the possible basic colours smeared out. The cross indicates the currently selected base colour.


The base colour can be further modified by adjusting the brightness (Luminosity) with this selection box.


This Marker indicates the currently selected luminosity.


This gives an indication of the colour selected, on the left the colour is generated by dithering (mixing of different colour dots) to achieve a result. On the right the nearest solid colour available to the screen is chosen.

Dithered colours tend to look grainy and make the screen difficult to read if they are used as a background to text.


Hue Saturation and Luminosity.

This is a system used to approximate colours by specifying 3 components:

Hue - the basic colour (think of selecting a single colour from a rainbow). Acceptable values are in the range 0 to 239

Saturation - Saturated colours are strong concentrated colours. Unsaturated colours are washed out natural colours. Acceptable values are in the range 0 (unsaturated) to 240 (saturated).

Luminosity - How bright the colour is, the brightest colours always appear white, the darkest always appear black. Acceptable values are in the range 0 (black) to 240 (white).

This is only an approximation to true colour, and since these colours are drawn on an Red/Green/Blue screen, the approximation may not produce the same results on screen as on even the best colour printer - colour is subjective.


Red Green Blue

This is a system of selecting colours by mixing different intensities of red, green and blue. This is how the colour display works and hence this system is more natural for the computer, rather than for the user.

Acceptable values for each colour are from 0 (off) to 255 (maximum intensity).


Add to Custom Colours - the colour currently displayed in the right section of the dialogue is added to the Custom Colours palette in the left section.


Font Dialog
Font

Introduction

The Font dialogue selects the typeface, style and colour for text displayed within CleanSheet. This is a standard system dialogue so it appears again and again throughout CleanSheet.

Click on any part you need help with.


The base typeface is selected from this list, this defines the basic style of the text. Typefaces with the [image] symbol before them are True Type typefaces that can be scaled smoothly to any size. Whenever possible you should use these typefaces.


The styles that the base typeface is available in are listed in this section. The exact wording depends on the supplier of the typefaces, but generally Italic typefaces are called Cursive, Italic or Oblique and the weights (how heavy or black a typeface is) generally follows a trend:

Light [image] Roman [image] Regular [image] Medium [image] Demi Bold [image] Bold [image] Black

With typefaces that aren't TrueType, the system may simulate the typeface by (for example) skewing a regular typeface to obtain an italic.


Size - The size of the typeface in Points (72nds of an Inch). 10pt is the regular text size for editing. If the typeface isn't True Type, then the equivalent bitmap typeface may have to be stretched to make it larger producing a jagged look.


Strikeout 	A horizontal line is drawn through the middle of the text.

Underline	A single underline is drawn under the text.


Colour - The colour that the typeface is drawn in. The colour must be a solid pallet colour, hence this list box only lists solid colours.


A sample of the typeface and some explanatory text are provided in this section of the dialogue.


Open Dialog
Open

Introduction

The Open dialogue is for selecting the file to be loaded from disk and displayed in CleanSheet.

The Drive

Each floppy disk and each hard disk is called a Drive. Floppy disks are always labeled A (and B if you have 2 floppy disks), hard disks are labeled C, D, E.. and so on. If the file is only floppy disk A, then you would select disk A in the Drives section.

Select the Drive the file is on.

Directories

On each drive is a hierarchy of folders. These split up the disk into a logical manner, so that related files are grouped together in one folder. The directory specifies where in this system of folders you are, for example "c:\c700\source" reading left to right means Drive C:, inside the folder called "c700", inside the folder "source".

Notice the hierarchy of folder, the folder "source" is inside the folder "c700".

Select the folder the file is in.

Filenames

Each file is referred to by a name, with an extension (a full stop followed by 3 characters) after it. The extension tells the system what kind of file it is. CleanSheet uses the extensions .CLN for its main files and .CBK for its backup files.

When this dialogue is first opened, the File Name is given as *.CLN, the star (*) means all filenames, and hence *.CLN means all filenames with the extension CLN. This text string tells the system to display all the files that end in .CLN that are in this folder.

Select the file from the list of displayed files.

Click on any part of the dialogue you need further help with.

See Also the Help Available with the Windows File Manager.


File Name

Enter the name of the file in this section (you can omit the extension). You can also enter a file mask, for example *.CBK means all files ending in extension CBK, *.* means all files with all extensions.


A list of the files in this folder is displayed here. Only files that conform to the file mask are displayed. For example if the File Name is *.CLN, then only files with the extension CLN are displayed.


Types of Files

Select which file type to display here. Each file type has a corresponding file extension, hence selecting the WorkSheets file type, puts *.CLN in the filename field so that only CleanSheet WorkSheets (which always end in .CLN) are displayed.


Directories

This section displays the current directory, and provides a graphical list showing the directory tree.

In this list, open folders are shown as [image], closed folders are shown as [image].

To open a folder and see what's inside, double click on its icon.

Notice the indent indicating the levels of folders.

This for example means that folder "MsApps" is inside the "Windows" folder which is inside Drive C.


Drives - this section lists the floppy disk drives and hard disks drives available to store files on.


Read Only

If this button is selected, then the file is opened as without a filename. You can still edit the sheet, but when you attempt to save it, you will be prompted for a new filename.


Save As Dialog
Save As

Introduction

This dialogue sets the filename under which the sheet is saved. It is almost identical to the dialogue for Opening a file and for this reason, you should read the section on the Open Dialog first.

Step - by Step

Select the Drive to save to.

Select the Directory to save to.

Enter the Filename the sheet is to be saved as. Choose a filename that will help you identify the file when you wish to open it again. You are allowed only 8 characters for a filename, you do not have to add the .CLN extensions to identify it as a CleanSheet worksheet, CleanSheet will do this.

If backup copies are to be kept, or the sheet is to be protected by a password, select the "Options" button.

Select OK to save the file.


Tags

Introduction

There are so many differing objects within CleanSheet, a system of style sheets would be impossible - each object simply has such different settings. However there are areas of common ground and CleanSheet implements a system called Tag Names to allow you to use them.

Essentially Tags allows you to restyle groups of differing objects all at once.

How it Works

CleanSheet has a pool of dialogues that affect objects. When an object is selected, the dialogues that have any affect on that object are listed on the Object menu.

A lot of the dialogues have an affect on more than one type of object. When two objects are selected, if those two objects share a common dialogue, then the dialogue is only listed once.

The settings you enter onto that single common dialogue apply to all the selected objects that accept those settings.

Style Tag Names

Every object can have one or more Tag Names, these are set by the Object Attributes dialogue. Using the Tag names, you can select a group of objects quickly.

This is done using the Select Special dialogue, each object can have one or more Tag Names, select special will select any object that contains any one of the required tag names.

Special Notes

Tags only operate in Edit Mode, in Use Mode only one object can be selected and hence tags are inappropriate.


Window Management

Introduction

This topics deals with the view of sheets and the handling of view windows.

Window Panes

Every window onto a sheet can be scrolled to view different areas - but what if you want to see two areas of the sheet at the same time and those two areas don't fit within the window?

This is where window panes come in - each window can be split into 1,2 or 4 different panes - each pane can be scrolled to view a separate part of the sheet.

The windows can be split vertically, horizontally or both.

To split a window:

Move the mouse over the split points.

Click and drag a split bar to the position you want

Release the mouse.

Removing a window split is just as simple, just drag the split all the way across to the left or right, top or bottom edge and release the mouse button - the split will be removed.

Scrolling Window Panes

Windows panes do not scroll completely independently - this would take two scroll bars per pane and simply take too much screen space.

Instead the panes are linked:

This still allows you to view different parts of the sheet, but without the extra overhead of all those scroll bars.

Multiple Windows

If the panes system does not offer enough flexibility you can create up to 8 different view windows onto a sheet.

To create a new view window, select New Window on the windows menu. To help you identify the windows, each view will have a number after its name, for example MySheet:1 is the first view window onto the file MySheet.

Each window scrolls independently.

Each window can have its own scale See Scale on the Settings menu.

Each window can display a different layer of the sheet.

This makes multiple windows very useful, for example you could display the sheet full size in one window for easy editing, and reduced in size in another (to get an overall view).


Menus

Introduction

There appear to be very few menus within CleanSheet, but this is highly deceptive. Most of the menu options are listed on the Object menu, these only appear when an object is selected and then only menus relevant to that object.

This system allows us to provide a heavy weight application without heavy weight menus to match. If you don't need a feature then you never see its menus.

For this reason the full list of possible items on the Object menu is not listed here. To find out about the menus for a particular object, select the object from the Pallette topic and read the section of the Object help named Dialogues Supported.

File Menu

This menu contains options that apply to a whole sheet.

New	Creates a new blank worksheet. This does not affect any other sheet you already have open, CleanSheet supports as many worksheets as your system memory will allow.

Open	Opens an existing sheet from disk. The sheet is selected by the Open File dialogue.

Close	Closes the top sheet window, if the window contains a sheet that has changed and the changes will be lost, CleanSheet will warn you and provide a chance to save the file first.

Save	Saves the file under its present name, this requires no further prompting from you unless the sheet doesn't have a name, in which case this is the same as Save As.

Save As	Saves the sheet under the name that you enter. This is used to save a new file that hasn't been named, rename an existing worksheet, or save the file in a different place on the disk. The Save As dialogue allows you to enter the name.

Print	Prints all or part of the sheet to the printer. There are many available options such as headings, page breaks and so on, these are set by the Print dialogue.

Print Setup	Sets the options specific to the printer.

Exit	Exit CleanSheet, if any sheets have changed, you will be warned and given an opportunity to save the sheet first.

Edit Menu

This menu contains items relevant to editing a sheet, or editing parts of an object.

Undo	Undoes the last change, selecting this option a second time will redo the change.

Cut	Cuts out the selected item and pastes it to the clipboard. In Edit Mode, it cuts the selected objects (and any pipes linking selected objects). In Use Mode, its action depends on the object, for details select the object on the Pallette topic and see the section on Clipboard Support.

Copy	Copies the selected item to the clipboard. In Edit Mode, it copies the whole of the selected objects and any linking pipes. In Use Mode, its action is dependent on the object, for details see the Clipboard Support section of the object's documentation.

Paste	Pastes the contents of the clipboard onto the sheet. In Edit Mode it pastes whole objects and any linking pipes. In Use Mode its action depends on the object.

Clear	Deletes the selected item, leaving the clipboard unchanged. This action can always be undone. In Edit Mode, it deletes whole objects and linking pipes, in Use Mode its action depends on the object.

Select Special	Selects multiple objects by their name, tags names, object type and layer. See the Select Special dialogue and tags. Multiple objects can only be selected in Edit Mode, in Use Mode this menu is disabled.

Paste Function	Pastes the name of a CleanSheet function into the Edit Text, the name is selected from a list on the Paste Function dialogue, this ensures that you have the correct brackets and parameters for that function. This menu item is only enabled when the Edit Field contains text that is being edited.

Settings Menu

Align Objects	The menus listed under this heading align the edges of selected objects - this improves the appearance of a sheet. Multiple objects can only be selected in Edit Mode and hence this option is only enabled in Edit Mode.

Pallette	Sets the style and layout of the pallette of objects. This is set using the Pallette Style dialogue.

Sheet View	Sets the styles used to display multiple layers, pipes and frames for the whole sheet. This is set using the Sheet View dialogue.

Pipe Options	Sets the style and colouring of pipes using the Pipe Options dialogue. The style set here applies to all of the pipes on the sheet.

Calculation Options	Defines how the sheet is calculated and how circular references are handled. See the Calculation Options dialogue.

Scale	Sets the scale of the top view window. Each view window can be independently scaled. See the Scale dialogue.

Status Line	Displays or hides the status line that appears at the bottom of the window. This line displays helpful messages, but you may prefer to have the extra screen space.

Edit Sheet Mode	Switches between Edit Mode and Use Mode, a tick indicates Edit Mode.

Object Menu

This contains all the menus specific to the object, or objects selected. For details on the menus available for each object, select the object on the Pallette topic and read the section under Dialogues Supported.

Window Menu

These menu items deal with managing the sheet windows. See Window Management for more information.

New Window	Creates a new view window onto a sheet.

Tile	Arranges all of the open windows into tiles so they don't overlap.

Cascade	Arranges the open windows so each overlaps the next in a diagonal cascade of windows.

Arrange Icons	Windows that have been minimised into icons are arranged into neat lines.

Help Menu

The only item on the Help menu that needs further explanation is the Advisor. This is a system for deciding which object to use for which problem, see Advisor dialogue for more information.


CleanSheet Operators

The following list of operators are available within CleanSheet.

+ Addition Operator

- Subtraction

* Multiplication Operator

/ Division Operator

% Percentage Operator

? Modulus Operator

^ Raise to the Power Operator

#& Bitwise AND Operator

#| Bitwise OR Operator

#~ Bitwise XOR Operator

#> Bitwise Right Shift Operator

#< Bitwise Left Shift Operator

! Factorial Operator


+ Addition Operator

The addition operator's exact action depends on the objects it operates on, the following gives an exact list, but you will generally find that addition operates sensibly, that is it behaves as you would expect addition to behave.

For a list of conventions used, see Conventions

Null + Any	Adding NULL to an object returns the object, e.g., 1 + NULL returns 1, "Smith" + NULL returns "Smith"

Integer +  Integer	Adding a integer value to an integer returns an integer, e.g. 1@ + 2@ returns 3@

Integer + Float	Adding an integer to a single real value, or a single real value to a single real value returns a single real value, e.g. 3@ + 0.142 returns 3.142,  6.234 + 1.766 returns 8.0

Integer + Double	Adding an integer, single real, or double real value to a double real value returns a double real value, e.g., if Pi := 3.141592654, then Pi + 3@ returns 6.141592654, Pi + 3.142 returns 6.283592654, while Pi + Pi returns 6.283185307.

Integer + String	Adding an integer to a string will add the character represented by the value (mod 256) to the start or end of the string, i.e. 65 + "Hello" returns "AHello", while "Hello" + 65 returns the string "HelloA".

Time + Numeric	Adding an integer, single real, or double real value to a time object returns the time object plus or minus the value in seconds, e.g. 10:23:59 + 200@ returns 10:26:19.

Complex + Numeric	Adding an integer, single real, double real, time or complex number to a complex number returns a complex number, e.g. 10+2j + 10@ returns 20+2j.  If a time object is used, then the time object is converted to an absolute number of seconds since midnight and then added as a number, i.e. MyComplex + 10:24:04pm returns 80654+2j (80644 seconds since midnight)

Boolean + Numeric	Adding a Boolean object to any object (except NULL) is equivalent to adding the value 0 (for FALSE) or 1 (for TRUE).

String + String	Adding a string object to a string object returns the concatenated strings, e.g. "Hi" + "There" returns "Hi There".

Date + Numeric	Adding an integer, single real, or double real value to a date object returns the date object plus N days, e.g. \12th Jan 74 + 12 returns \24th Jan 1974

Error + Any Object	Adding an error object to any other object returns the error object.

Array Objects

Adding an object to an array object is equivalent to adding the object to each of the array elements in turn.  When adding two array objects, each dimension is treated separately; for arrays of the same size and dimensions, corresponding values are simply added for each element.  For example

Note that arrays may not just contain numbers, they could hold string elements, or even whole lists or arrays within each element being looked at.


Cog Calculation Object
 Cog Calculation

Introduction

The COG object (Corresponding Objects Grid) performs calculations on sections of input two dimensional arrays to produce a result two dimensional array. It performs calculations along the lines of 'multiply this row by that column and place the result in this column of the result'. It can perform several such calculations in one go.

For an example of the Working of the Cog object, see How Cog Works.

A Cog object has 3 main elements:

The size of the result array, set by the Cog Output Size Dialogue

The Equations, set by the Cog Type dialogue.

The Inputs used in the calculation (set by the Number of Inputs dialogue)

These three elements define how a Cog object works.

The Cog object is much simpler to program if you have entered sample data into your sheet and recalculated the sheet. Under these circumstances, there is data in the pipes and the Cog dialogue can display this data when you are constructing Cog equations.

Cog Equations

A Cog object is defined by a group of equations, set by the Type of Cog dialogue. A typical equation might look like this:

Area: All, Equation: A[dx][dy]+B[dx][dy]

When this equation is being calculated, the Cog object calculates each element of the result, column-by-column, row-by-row of the affected area. In this example the affected area is All of the result array.

For each cell it sets dx to be the column offset into the affected area. If the affected area was column 3 to column 5, then when calculating the result for column 4, dx would be 1 (4-3=1).

Similarly, for each cell calculated dy is set to be the offset in rows from the top of the affected area to the cell.

The equation is evaluated, for this example the first cell would have dx=0 & dy=0 and hence the equation for that cell would be A[0][0]+B[0][0] which is column 0, row 0 of array A + column 0, row 0 of input array B.

The result is from this calculation is placed in the appropriate cell of the result.

Example: If you wanted column 0 of the result to be column 0 of A added to column 0 of B, the equation would look like this:

Area: Column 0, Equation A[0][dy]+B[0][dy]

Notice that A[0] is the first column. For two dimensional arrays A[column][row] gives the element (column, row), and hence A[0][dy] gives (column 0, row dy).

Notice that corresponding elements are added, and that only column 0 of A and B takes part in the result, because our equation only included column 0.

Now the good news, you do not phrase these inputs with all their dx's and dy's yourself - the Paste Input dialogue available on the Cog Type dialogue does this for you.

In the above example you would take the following steps:

Select Cog Type on the Object menu.

Select Set Area and set the affected area of the result to column 0 (you can do this by double clicking on column 0), Select OK.

Select Paste Input, we want to add column 0 of A, so select Input A and double click on column 0. Select OK.

The equation will now be A[0][dy].

We want to add, so enter a + symbol after the A[0][dy].

Select Paste Input again, this time be want column 0 of B, so select Input B and double click on column 0. Select OK.

We now have to add the equation to the list in the Cog object, so click on ADD.

Finally click on OK and we have our example defined.

How To

This section lists some examples of uses for the Cog object, it is a tiny fraction of the possibilities for this object, it represents the most common uses for this object.

Sum	How to calculate the sum of a section from a table.

Multiply	Multiply along a row.

Frame Style

The inlets are either side of the frame, only one inlet A can be connected and one inlet B, and so on, the reason there are two of each inlet type is simply to make it easier to plumb this object in.

This example shows 6 inlets, the frame expands to allow for more inlets.

The outlets are top and bottoms, they carry the result of the Cog equations - any number of pipes can be taken off these.

Usage Example

The file Density.cln contains and example of a Cog object.

Consistent

A Cog object is consistent if the equations it contains produce the same results for the same inputs.

When CleanSheet evaluates a sheet, if a pipe comes from a Consistent object and the object's inputs haven't changed, then the pipe won't have changed and hence CleanSheet will not recalculate the pipe. This system is called Sparse Recalculation and it speeds up the calculating of a sheet.

An inconsistent equation is one that includes some unpredictable element, such as the Rand function, the Now function and similar functions that give different result each time they are evaluated.

To select Consistent, switch to Use Mode and select it on the object menu. The default is a consistent object (indicated by a tick), no tick means inconsistent.

Dialogues supported

 Object Attributes	Sets the object's tags and name

 Number of Inputs	Sets the number of inlets pipe

 Cog Type	Sets the Cog equations.

 Cog Output Size	Sets the size of the result array

Special Notes

When all you want to do is simply add corresponding array elements, or perhaps divide each element by a constant, then you should remember that most operators can handle arrays. For example A+B will add corresponding elements of A and B if they are both arrays. Similar A/3 will divide all elements in array A by the number 3.

This means that quite often a simple Calculator object will do.


This simply sets how many inputs A, B...Z are allowed. Up to 26 are allowed on a Cog object.


Cog Object - Summing
How to Sum with a Cog Object

Introduction

Quite often you want to calculate the sum of a section from a table (a table is a two dimensional array). You could do this using a Dissector Object (to extract the section to be summed) together with a Summation object (to do the summation), but sometimes you may want to embed this calculation inside a Cog object.

A phrase in an equation that would do this looks like:

sum(extract{A,{0,0},{30,30})

The extract function extracts the elements from {0,0} to {30,30} from the input array A.

The Sum function then sums the elements of this array to generate a total.

Example Cog Object

The Cog object dialogue constructs these phrases for you. For example, imagine that input A into the Cog object contains a table of rainfall data for Northern and Southern England.

You want to construct an array containing the total rainfall for Northern and Southern England, together with headings, like this:

The Cog object is much simpler to program if you have entered sample data into your sheet and recalculated the sheet. Under these circumstances, there is data in the pipes and the Cog dialogue can display this data when you are constructing Cog equations.

First set the size of the output array.

Select the Cog Object on the sheet

Select the Cog Output Size dialogue from the Object menu.

The table has a fixed height and fixed width of 2, so select the Fixed width and Fixed height options and enter 2 into the edit field next to them.

Click on OK

The next thing to do is to define the headings

Select 'Type of Cog' to define the Cog Equations.

Select 'Set Area' to define where the first heading is

Click on the top left corner cell and select OK.

The Cog equation dialogue now says Area {0,0,0,0}

Enter the equation "North" (including the double quotes) and click on Add to add it to the list

The other heading is very similar

Select 'Set Area' to define where the heading is

Click on the second from top cell and select OK

The Cog equation dialogue now says Area {0,1,0,1}

Enter the equation "South" and click on Add to add it to the list

Next we are going to add equations that calculate the sum of the columns.

Select 'Set Area' and click on the box to contain the sum of Northern Rainfall, and select OK

The Cog equation dialogue should read Area {1,0,1,0}

Select Paste Input, and select the area Left:0, Top: 1,  to Right: 0, Bottom Edge.

The button 'Sum the Area to Produce a Single Summation' should be selected.

Select OK.

The phrase sum(extract{A,{0,1},{0,32000}}) is inserted into the equation, this is the equation required to sum that section of Input A.

Click on Add to add the equation to the list

Next comes the equation to calculate the sum of the Southern Rainfall.

Select 'Set Area' and click on the box to contain the sum of Southern Rainfall, and select OK

The Cog equation dialogue should read Area {1,1,1,1}

Select Paste Input, and select the area Left:1, Top: 1,  to Right: 1, Bottom Edge.

The button 'Sum the Area to Produce a Single Summation' should be selected.

Select OK.

The phrase sum(extract{A,{1,1},{1,32000}}) is inserted into the equation, this is the equation required to sum that section of Input A.

Click on Add to add the equation to the list

This Cog object is now ready for use.


Cog: Multiplying along Rows
Multiplying along Rows

Introduction

The Product Object provides a range of calculations for multiplying along rows and columns, however there are times when you want to do this as part of a Cog object.

Example Cog Object

Consider the example below, Input A is a table of ingredients for a Compost manufacturer, showing how much Soil, Compost, Minerals and Filler are used in each of the 4 compost mixtures. Headings have been added to help you understand the data, these are not part of the data.

Input B is the amount of each compost sold.

We want to calculate a table showing how much of each ingredient has been used for each Compost mix:

Normally the first thing to do is to set the size, but for this example the default size is fine.

Next we define the equation

Select Type of Cog.

We do not need to Set the Affected area, because the default (All of the result) is correct.

The calculation is All of Input A multiplied by the first column of Input B

Click on Paste Input

Select 'Input A', and select all of the area

Select 'Row by Row, Column by Column'. When the Cog object refers to this input, it will look at the elements that correspond row-by-row and column-by-column to the result.

Click on 'OK'

Enter a multiplication symbol *

Select 'Paste Input', this time select Input 'B', and double click in the centre of the first column to select it.

Select 'row-by-row, column-by-column'

Click on 'OK', when Cog refers to this input, it only has one column, so this column will be used over and over again across the whole result.

Click on Add to add the equation to the list, and select OK.

All of the calculating is done by one equation

A[dx][dy]*B[0][dy]

As the Cog object calculates each cell of the result, it changes dx and dy. Notice that B[0][dy] does not use dx, and hence only the first column (column 0) of B is used.


File Formats - Dialog
File Formats

Introduction

CleanSheet can import and export a wide range of file formats. This dialogue selects which file format to import or export.

Tabbed Text	Each column of data is separated by tabs, and each row starts a new line. Files in this format usually have extension .TXT.

Comma Delimited Text	Each column of data is separated by a comma, and each row begins a new line. If the data is a string of text, it is enclosed in double quotation marks. Files in this format usually have extensions .CSV

DIF	Data Interchange Format, this format is common in spreadsheets, it is a text format used for exchanging tables of data. This format is defined by Lotus Developments Corp. Files in this format have extensions .DIF

SYLK	Symbolic Link Format, common in spreadsheets, again this is a text format used to exchange tables of data. This format is defined by Microsoft Corporation. Files in this format have extensions .SLK.

Tabbed DOS Text	This format is identical to the normal Tabbed Text format, with the exception that the DOS character set is used rather than the Windows (so called ANSI) character set. Use this format when importing or exporting to DOS products, use the normal Tabbed Text when importing or exporting from Windows products.

Comma Delimited DOS Text	This format is identical to the Comma Delimited Text above, but uses the DOS character set rather than the Windows character set.

DIF - DOS Text	This format is the same as normal DIF, but uses the DOS character set instead of the Windows character set.

SYLK - DOS Text	This format is the same as normal SYLK, but uses the DOS character set instead of the Windows character set.

Note: Use the normal file formats when exchanging data with Windows Programs, and the DOS variants when exchanging data with DOS applications. This has an effect on character symbols such as £ that are in the extended character set.

Objects Affected

Input Table

Output Table


Importing Data

Importing a File into an Input Table

Switch to USE mode.

Click on the frame of the Input Table to selected it

Alternatively click to position the highlighted cell in the input table. This cell will become the top left corner of the imported data.

Select 'Import Data from File' on the Object menu.

Select the File to Import.

Select the Format of the File (see File Formats).

The File will be brought into the Input Table and if necessary the Input Table will be enlarged to accommodate the extra data.

See Also

Exporting Data


Exporting Data

Exporting a File from an Output Table

Switch to USE mode.

Click on the frame of the Output Table to selected it

Alternatively if you only want to export a section of the table, select that section.

Select 'Export Data to File' from the Object menu.

Select the Format of the File (see File Formats).

Enter the Name of the File to Export To.

The Output Table (or the selected section of the Output Table) will be written to the file in the requested format.

See Also

Importing Data